mirror of
https://git.openafs.org/openafs.git
synced 2025-01-19 07:20:11 +00:00
14408c7e88
Byte range locks:
The OpenAFS Windows client has to fake byte range locks given no
server side support for such locks. This is implemented as keyed
byte range locks on the cache manager.
Keyed byte range locks:
Each cm_scache_t structure keeps track of a list of keyed locks.
The key for a lock is essentially a token which identifies an owner
of a set of locks (referred to as a client). The set of keys used
within a specific cm_scache_t structure form a namespace that has a
scope of just that cm_scache_t structure. The same key value can
be used with another cm_scache_t structure and correspond to a
completely different client. However it is advantageous for the
SMB or IFS layer to make sure that there is a 1-1 mapping between
client and keys irrespective of the cm_scache_t.
Assume a client C has key Key(C) (although, since the scope of the
key is a cm_scache_t, the key can be Key(C,S), where S is the
cm_scache_t. But assume a 1-1 relation between keys and clients).
A byte range (O,+L) denotes byte addresses (O) through (O+L-1)
inclusive (a.k.a. [O,O+L-1]). The function Key(x) is implemented
through cm_generateKey() function for both SMB and IFS.
The cache manager will set a lock on the AFS file server in order
to assert the locks in S->fileLocks. If only shared locks are in
place for S, then the cache manager will obtain a LockRead lock,
while if there are any exclusive locks, it will obtain a LockWrite
lock. If the exclusive locks are all released while the shared
locks remain, then the cache manager will downgrade the lock from
LockWrite to LockRead.
Lock states:
A lock exists iff it is in S->fileLocks for some cm_scache_t
S. Existing locks are in one of the following states: ACTIVE,
WAITLOCK, WAITUNLOCK, LOST, DELETED.
The following sections describe each lock and the associated
transitions.
1. ACTIVE: A lock L is ACTIVE iff the cache manager has asserted
the lock with the AFS file server. This type of lock can be
exercised by a client to read or write to the locked region (as
the lock allows).
1.1 ACTIVE->LOST: When the AFS file server fails to extend a
server lock that was required to assert the lock.
1.2 ACTIVE->DELETED: Lock is released.
2. WAITLOCK: A lock is in a WAITLOCK state if the cache manager
grants the lock but the lock is yet to be asserted with the AFS
file server. Once the file server grants the lock, the state
will transition to an ACTIVE lock.
2.1 WAITLOCK->ACTIVE: The server granted the lock.
2.2 WAITLOCK->DELETED: Lock is abandoned, or timed out during
waiting.
2.3 WAITLOCK->LOST: One or more locks from this client were
marked as LOST. No further locks will be granted to this
client until al lost locks are removed.
3. WAITUNLOCK: A lock is in a WAITUNLOCK state if the cache manager
receives a request for a lock that conflicts with an existing
ACTIVE or WAITLOCK lock. The lock will be placed in the queue
and will be granted at such time the conflicting locks are
removed, at which point the state will transition to either
WAITLOCK or ACTIVE.
3.1 WAITUNLOCK->ACTIVE: The conflicting lock was removed. The
current serverLock is sufficient to assert this lock, or a
sufficient serverLock is obtained.
3.2 WAITUNLOCK->WAITLOCK: The conflicting lock was removed,
however the required serverLock is yet to be asserted with the
server.
3.3 WAITUNLOCK->DELETED: The lock is abandoned or timed out.
3.5 WAITUNLOCK->LOST: One or more locks from this client were
marked as LOST. No further locks will be granted to this
client until all lost locks are removed.
4. LOST: A lock L is LOST if the server lock that was required to
assert the lock could not be obtained or if it could not be
extended, or if other locks by the same client were LOST.
Effectively, once a lock is LOST, the contract between the cache
manager and that specific client is no longer valid.
The cache manager rechecks the server lock once every minute and
extends it as appropriate. If this is not done for 5 minutes,
the AFS file server will release the lock. Once released, the
lock cannot be re-obtained without verifying that the contents
of the file hasn't been modified since the time the lock was
released. Doing so may cause data corruption.
4.1 LOST->DELETED: The lock is released.
4.2 LOST->ACTIVE: The lock is reassertd. This requires
verifying that the file was not modified in between.
4.3 LOST->WAITLOCK: All LOST ACTIVE locks from this client were
reasserted. The cache manager can reinstate this waiting
lock.
4.4 LOST->WAITUNLOCK: All LOST ACTIVE locks from this client
were reasserted. The cache manager can reinstate this waiting
lock.
5. DELETED: The lock is no longer relevant. Eventually, it will
get removed from the cm_scache_t. In the meantime, it will be
treated as if it does not exist.
5.1 DELETED->not exist: The lock is removed from the
cm_scache_t.
6* A lock L is ACCEPTED if it is ACTIVE or WAITLOCK.
These locks have been accepted by the cache manager, but may or
may not have been granted back to the client.
7* A lock L is QUEUED if it is ACTIVE, WAITLOCK or WAITUNLOCK.
8* A lock L is EFFECTIVE if it is ACTIVE or LOST.
9* A lock L is WAITING if it is WAITLOCK or WAITUNLOCK.
Lock operation:
A client C can READ range (Offset,+Length) of cm_scache_t S iff:
1. for all _a_ in (Offset,+Length), one of the following is true:
1.1 There does NOT exist an ACTIVE lock L in S->fileLocks such
that _a_ in (L->LOffset,+L->LLength) (IOW: byte _a_ of S is
unowned)
AND
For each LOST lock M in S->fileLocks such that
_a_ in (M->LOffset,+M->LLength), M->LockType is shared AND
M->key != Key(C).
(Note: If this is a different client from one whose shared
lock was LOST, then the contract between this client and the
cache manager is indistinguishable from that where no lock
was lost. If an exclusive lock was lost, then the range is
considered unsafe for consumption.)
1.3 There is an ACTIVE lock L in S->fileLocks such that: L->key
== Key(C) && _a_ in (L->LOffset,+L->LLength) (IOW: byte _a_
of S is owned by C under lock L)
1.4 There is an ACTIVE lock L in S->fileLocks such that _a_ in
(L->LOffset,L->+LLength) && L->LockType is shared (IOW: byte
_a_ of S is shared) AND there is no LOST lock M such that _a_
in (M->LOffset,+M->LLength) and M->key == Key(C)
A client C can WRITE range (Offset,+Length) of cm_scache_t S iff:
2. for all _a_ in (Offset,+Length), one of the following is true:
2.1 Byte _a_ of S is unowned (as above) AND for each LOST lock
L in S->fileLocks _a_ NOT in (L->LOffset,+L->LLength).
2.2 Byte _a_ of S is owned by C under lock L (as above) AND
L->LockType is exclusive.
A client C can OBTAIN a lock L on cm_scache_t S iff:
3. for all _a_ in (L->LOffset,+L->LLength), ALL of the following is
true:
3.1 L->LockType is exclusive IMPLIES there does NOT exist a QUEUED lock
M in S->fileLocks such that _a_ in (M->LOffset,+M->LLength).
(Note: If we count all QUEUED locks then we hit cases such as
cascading waiting locks where the locks later on in the queue
can be granted without compromising file integrity. On the
other hand if only ACCEPTED locks are considered, then locks
that were received earlier may end up waiting for locks that
were received later to be unlocked. The choice of QUEUED
locks were made so that large locks don't consistently get
trumped by smaller locks which were requested later.)
3.2 L->LockType is shared IMPLIES for each QUEUED lock M in
S->fileLocks, if _a_ in (M->LOffset,+M->LLength) then
M->LockType is shared.
4. For each LOST lock M in S->fileLocks, M->key != Key(C)
(Note: If a client loses a lock, it loses all locks.
Subsequently, it will not be allowed to obtain any more locks
until all existing LOST locks that belong to the client are
released. Once all locks are released by a single client,
there exists no further contract between the client and AFS
about the contents of the file, hence the client can then
proceed to obtain new locks and establish a new contract.)
A client C can only unlock locks L in S->fileLocks which have
L->key == Key(C).
The representation and invariants are as follows:
- Each cm_scache_t structure keeps:
- A queue of byte-range locks (cm_scache_t::fileLocks) which
are of type cm_file_lock_t.
- A record of the highest server-side lock that has been
obtained for this object (cm_scache_t::serverLock), which is
one of (-1), LockRead, LockWrite.
- A count of ACCEPTED exclusive and shared locks that are in the
queue (cm_scache_t::sharedLocks and
cm_scache_t::exclusiveLocks)
- Each cm_file_lock_t structure keeps:
- The type of lock (cm_file_lock_t::LockType)
- The key associated with the lock (cm_file_lock_t::key)
- The offset and length of the lock (cm_file_lock_t::LOffset
and cm_file_lock_t::LLength)
- The state of the lock.
- Time of issuance or last successful extension
Semantic invariants:
I1. The number of ACCEPTED locks in S->fileLocks are
(S->sharedLocks + S->exclusiveLocks)
External invariants:
I3. S->serverLock is the lock that we have asserted with the
AFS file server for this cm_scache_t.
I4. S->serverLock == LockRead iff there is at least one ACTIVE
shared lock, but no ACTIVE exclusive locks.
I5. S->serverLock == LockWrite iff there is at least one ACTIVE
exclusive lock.
I6. If a WAITUNLOCK lock L exists in S->fileLocks, then all
locks that L is waiting on are ahead of L in S->fileLocks.
I7. If L is a LOST lock, then for each lock M in S->fileLocks,
M->key == L->key IMPLIES M is LOST or DELETED.
--asanka
====================
This delta was composed from multiple commits as part of the CVS->Git migration.
The checkin message with each commit was inconsistent.
The following are the additional commit messages.
====================
Byte range locks added to change list
====================
should improve error codes, and allow lock promotions and demotions
by releasing locks.
====================
More improvements to the byte range locking. Handle errors caused
by a failure to have locking privs; report sharing violations when
opening files; lie about locks on read-only volumes; implement
shared read/write file creation in the smb layer.
====================
remove assertion
====================
must reference count local references to objects if the lock
is being released
====================
Do not use a variable until you assign it a value
====================
remove an unwanted assertion and move the resetting of scp->serverLock
to -1 into cm_LockMarkSCacheLost() so that others do not forget to set
it. cm_LockMarkSCacheLost() is always called when the scp->mx is held
so it is ok to do so.
|
||
|---|---|---|
| doc | ||
| src | ||
| .cvsignore | ||
| .splintrc | ||
| acconfig.h | ||
| acinclude.m4 | ||
| config.guess | ||
| config.sub | ||
| configure-libafs.in | ||
| configure.in | ||
| INSTALL | ||
| install-sh | ||
| libafsdep | ||
| Makefile-libafs.in | ||
| Makefile.in | ||
| missing | ||
| mkinstalldirs | ||
| NEWS | ||
| README | ||
| README-NT | ||
| README-WIN9X | ||
| README.CVS | ||
| README.DEVEL | ||
| README.OBSOLETE | ||
| README.SECURITY | ||
| regen.sh | ||
Copyright 2000, International Business Machines Corporation and others.
All Rights Reserved.
This software has been released under the terms of the IBM Public
License. For details, see the LICENSE file in the top-level source
directory or online at http://www.openafs.org/dl/license10.html
Short instructions for sites upgrading from a previous version of AFS:
% ./configure --enable-transarc-paths
% make
% make dest
will create a Transarc-style dest tree in ${SYS_NAME}/dest where
${SYS_NAME} is the AFS sysname of the system you built for.
This assumes if you're building for Linux that your kernel source is
in /usr/src/linux.
Otherwise, please read on.
Building OpenAFS on UNIX and LINUX
----------------------------------
A. Creating the proper directory structure.
Uncompress the source into a directory of your choice. A directory
in afs space is also valid. In the directory that you uncompressed the
source in, you will only have an src/ directory.
1. Pick a system to build for, and note its default AFS sys_name.
A directory will be automatically created for binaries to be written
into with this name when you build.
alpha_dux40
alpha_dux50 (only tested on 5.0A, does not work with 5.1)
i386_fbsd_42, i386_fbsd_43, i386_fbsd_44, i386_fbsd_45,
i386_fbsd_46, i386_fbsd_47, i386_fbsd_50, i386_fbsd_51,
i386_fbsd_52, i386_fbsd_53, i386_fbsd_60
i386_linux22, i386_linux24, i386_linux26
i386_umlinux22, i386_umlinux24
i386_obsd31, i386_obsd32, i386_obsd33, i386_obsd34, i386_obsd35,
i386_obsd36, i386_obsd37, i386_obsd38
rs_aix42
sgi_65 (file server not tested)
sun4_413 (No client support, no fileserver support, db servers only)
sun4x_56, sun4x_57, sun4x_58, sun4x_59 (logging UFS not supported
for mixed-use partitions containing client cache)
ppc_darwin_70
ppc_linux22, ppc_linux24
alpha_linux22, alpha_linux24
ia64_linux24, ia64_linux26
sparc_linux22, sparc_linux24
sparc64_linux22, sparc64_linux24
hp_ux110 (See notes below for information on getting missing header)
hp_ux102 (Client port possible, but db servers and utilities work)
2. Using configure in the top level directory, configure for your
AFS system type, providing the necessary flags:
% ./configure --with-afs-sysname=sun4x_58 --enable-transarc-paths
For some systems you need also provide the path in which your kernel
headers for your configured kernel can be found. See the
system-specific Notes sections below for details.
Be prepared to provide the switches --enable-obsolete and
--enable-insecure if you require the use of any bundled but obsolete
or insecure software included with OpenAFS. See README.obsolete and
README.insecure for more details.
There are two modes for directory path handling: "Transarc mode" and "default mode":
- In Transarc mode, we retain compatibility with Transarc/IBM AFS tools
by putting client configuaration files in /usr/vice/etc, and server
files in /usr/afs under the traditional directory layout.
- In default mode, files are located in standardized locations, usually
under $(prefix).
- Client programs, libraries, and related files always go in standard
directories under $(prefix). This rule covers things that would go
into $(bindir), $(includedir), $(libdir), $(mandir), and $(sbindir).
- Other files get located in the following places:
Directory Transarc Mode Default Mode
============ ========================= ==============================
viceetcdir /usr/vice/etc $(sysconfdir)/openafs
afssrvdir /usr/afs/bin (servers) $(libexecdir)/openafs
afsconfdir /usr/afs/etc $(sysconfdir)/openafs/server
afslocaldir /usr/afs/local $(localstatedir)/openafs
afsdbdir /usr/afs/db $(localstatedir)/openafs/db
afslogdir /usr/afs/logs $(localstatedir)/openafs/logs
afsbosconfig $(afslocaldir)/BosConfig $(afsconfdir)/BosConfig
afsbosserver $(afsbindir)/bosserver $(sbindir)/bosserver
B Building
1. Now, you can build OpenAFS.
% make
2. Install your build using either "make install" to install
into the current system (you will need to be root, and files
will be placed as appropriate for Transarc or standard paths),
"make install DESTDIR=/some/path" to install into an alternate
directory tree, or if you configured with --enable-transarc-paths
make dest to create a complete binary tree in the dest directory
under the directory named for the sys_name you built for,
e.g. sun4x_57/dest or i386_linux22/dest
2. As appropriate you can clean up or, if you're using Linux, build for
another kernel version.
To clean up:
% make clean
C Problems
If you have a problem building this source, you may want to visit
http://www.openafs.org/ to see if any problems have been reported
or to find out how to get more help.
Mailing lists have been set up to help; More details can be found
on the openafs.org site.
D Linux Notes
For Linux systems you need also provide the path in which your
kernel headers for your configured kernel can be found. This should
be the path of the directory containing a child directory named
"include". So if your version file was
/usr/src/linux/include/linux/version.h you would invoke:
% ./configure --with-afs-sysname=i386_linux24 --with-linux-kernel-headers=/usr/src/linux
Currently you can build for only one Linux kernel at a time,
and the version is extracted from the kernel headers in the root
you specify.
To build for another Linux kernel version:
the system type defined in step A1.
% ./configure --with-afs-sysname=i386_linux24 --with-linux-kernel-headers=/usr/src/linux-2.2.19-i686
% make
Your dest tree will now include an additional kernel module for your
additional kernel headers. Be aware that if the kernel version string
which UTS_RELEASE is defined to in include/linux/version.h matches the
last kernel you built for, the previous kernel module will be
overwritten.
E HP-UX 11.0 Notes
HP-UX 11.0 requires a header called vfs_vm.h which HP has provided on their
web site: http://h21007.www2.hp.com/dspp/tech/tech_TechSoftwareDetailPage_IDX/1,1703,687,00.html
To navigate down from the top level of the portal, one would do
www.hp.com/dspp -> i want to... -> download software -> operating systems
to get to the same page.
F OpenBSD Notes
You need kernel source installed to build OpenAFS. Use the
--with-bsd-kernel-headers= configure option if your kernel source is not
in /usr/src/sys.
There is a package builder in src/packaging/OpenBSD. "sh buildpkg.sh"
should make a package for the client. Use pkg_add to install. The
package will install using transarc-paths, regardless of how you
configured. The package builder does not work on OpenBSD 3.5 and later
due to the incompatible re-write of pkg_create.
There is no server package, but I am told that "make install" will put
server binaries in /usr/afs.
Your kernel may panic when you try to shutdown after running the OpenAFS
client. To prevent this, change the "dangling vnode" panic in
sys/kern/vfs_syscalls.c to a printf and build a new kernel.
You can't run arla and OpenAFS at the same time.
G FreeBSD Notes
The FreeBSD client is very new and untested. Do not trust it for
production work.
You need kernel source installed to build OpenAFS. Use the
--with-bsd-kernel-headers= configure option if your kernel source is not
in /usr/src/sys.
You also need access to your kernel build directory for the opt_global.h
include file. Use the --with-bsd-kernel-build= configure option if your
kernel build is not GENERIC in the standard place.
There is a package builder in src/packaging/OpenBSD. "sh buildpkg.sh"
should make a package for the client. Use pkg_add to install. The
package will install using transarc-paths, regardless of how you
configured. The builder uses an old version of the /usr/vice/etc/rc file
that probably won't work. You might be able to replace it with something
like "kldload libafs.ko; /usr/vice/etc/afsd".
There is no server package, but I am told that "make install" will put
server binaries in /usr/afs.