[mirror_ubuntu-zesty-kernel.git] / Documentation / filesystems / dlmfs.txt

dlmfs
==================
A minimal DLM userspace interface implemented via a virtual file
system.

dlmfs is built with OCFS2 as it requires most of its infrastructure.

Project web page:    http://oss.oracle.com/projects/ocfs2
Tools web page:      http://oss.oracle.com/projects/ocfs2-tools
OCFS2 mailing lists: http://oss.oracle.com/projects/ocfs2/mailman/

All code copyright 2005 Oracle except when otherwise noted.

CREDITS
=======

Some code taken from ramfs which is Copyright (C) 2000 Linus Torvalds
and Transmeta Corp.

Mark Fasheh <mark.fasheh@oracle.com>

Caveats
=======
- Right now it only works with the OCFS2 DLM, though support for other
  DLM implementations should not be a major issue.

Mount options
=============
None

Usage
=====

If you're just interested in OCFS2, then please see ocfs2.txt. The
rest of this document will be geared towards those who want to use
dlmfs for easy to setup and easy to use clustered locking in
userspace.

Setup
=====

dlmfs requires that the OCFS2 cluster infrastructure be in
place. Please download ocfs2-tools from the above url and configure a
cluster.

You'll want to start heartbeating on a volume which all the nodes in
your lockspace can access. The easiest way to do this is via
ocfs2_hb_ctl (distributed with ocfs2-tools). Right now it requires
that an OCFS2 file system be in place so that it can automatically
find its heartbeat area, though it will eventually support heartbeat
against raw disks.

Please see the ocfs2_hb_ctl and mkfs.ocfs2 manual pages distributed
with ocfs2-tools.

Once you're heartbeating, DLM lock 'domains' can be easily created /
destroyed and locks within them accessed.

Locking
=======

Users may access dlmfs via standard file system calls, or they can use
'libo2dlm' (distributed with ocfs2-tools) which abstracts the file
system calls and presents a more traditional locking api.

dlmfs handles lock caching automatically for the user, so a lock
request for an already acquired lock will not generate another DLM
call. Userspace programs are assumed to handle their own local
locking.

Two levels of locks are supported - Shared Read, and Exclusive.
Also supported is a Trylock operation.

For information on the libo2dlm interface, please see o2dlm.h,
distributed with ocfs2-tools.

Lock value blocks can be read and written to a resource via read(2)
and write(2) against the fd obtained via your open(2) call. The
maximum currently supported LVB length is 64 bytes (though that is an
OCFS2 DLM limitation). Through this mechanism, users of dlmfs can share
small amounts of data amongst their nodes.

mkdir(2) signals dlmfs to join a domain (which will have the same name
as the resulting directory)

rmdir(2) signals dlmfs to leave the domain

Locks for a given domain are represented by regular inodes inside the
domain directory.  Locking against them is done via the open(2) system
call.

The open(2) call will not return until your lock has been granted or
an error has occurred, unless it has been instructed to do a trylock
operation. If the lock succeeds, you'll get an fd.

open(2) with O_CREAT to ensure the resource inode is created - dlmfs does
not automatically create inodes for existing lock resources.

Open Flag     Lock Request Type
---------     -----------------
O_RDONLY      Shared Read
O_RDWR        Exclusive

Open Flag     Resulting Locking Behavior
---------     --------------------------
O_NONBLOCK    Trylock operation

You must provide exactly one of O_RDONLY or O_RDWR.

If O_NONBLOCK is also provided and the trylock operation was valid but
could not lock the resource then open(2) will return ETXTBUSY.

close(2) drops the lock associated with your fd.

Modes passed to mkdir(2) or open(2) are adhered to locally. Chown is
supported locally as well. This means you can use them to restrict
access to the resources via dlmfs on your local node only.

The resource LVB may be read from the fd in either Shared Read or
Exclusive modes via the read(2) system call. It can be written via
write(2) only when open in Exclusive mode.

Once written, an LVB will be visible to other nodes who obtain Read
Only or higher level locks on the resource.

See Also
========
http://opendlm.sourceforge.net/cvsmirror/opendlm/docs/dlmbook_final.pdf

For more information on the VMS distributed locking API.
Commit	Line	Data
8df08c89 MF	1	dlmfs
	2	==================
	3	A minimal DLM userspace interface implemented via a virtual file
	4	system.
	5
	6	dlmfs is built with OCFS2 as it requires most of its infrastructure.
	7
	8	Project web page: http://oss.oracle.com/projects/ocfs2
	9	Tools web page: http://oss.oracle.com/projects/ocfs2-tools
	10	OCFS2 mailing lists: http://oss.oracle.com/projects/ocfs2/mailman/
	11
	12	All code copyright 2005 Oracle except when otherwise noted.
	13
	14	CREDITS
	15	=======
	16
	17	Some code taken from ramfs which is Copyright (C) 2000 Linus Torvalds
	18	and Transmeta Corp.
	19
	20	Mark Fasheh <mark.fasheh@oracle.com>
	21
	22	Caveats
	23	=======
	24	- Right now it only works with the OCFS2 DLM, though support for other
	25	DLM implementations should not be a major issue.
	26
	27	Mount options
	28	=============
	29	None
	30
	31	Usage
	32	=====
	33
	34	If you're just interested in OCFS2, then please see ocfs2.txt. The
	35	rest of this document will be geared towards those who want to use
	36	dlmfs for easy to setup and easy to use clustered locking in
	37	userspace.
	38
	39	Setup
	40	=====
	41
	42	dlmfs requires that the OCFS2 cluster infrastructure be in
	43	place. Please download ocfs2-tools from the above url and configure a
	44	cluster.
	45
	46	You'll want to start heartbeating on a volume which all the nodes in
	47	your lockspace can access. The easiest way to do this is via
	48	ocfs2_hb_ctl (distributed with ocfs2-tools). Right now it requires
	49	that an OCFS2 file system be in place so that it can automatically
a33f3224	50	find its heartbeat area, though it will eventually support heartbeat
8df08c89 MF	51	against raw disks.
	52
	53	Please see the ocfs2_hb_ctl and mkfs.ocfs2 manual pages distributed
	54	with ocfs2-tools.
	55
	56	Once you're heartbeating, DLM lock 'domains' can be easily created /
	57	destroyed and locks within them accessed.
	58
	59	Locking
	60	=======
	61
	62	Users may access dlmfs via standard file system calls, or they can use
	63	'libo2dlm' (distributed with ocfs2-tools) which abstracts the file
	64	system calls and presents a more traditional locking api.
	65
	66	dlmfs handles lock caching automatically for the user, so a lock
	67	request for an already acquired lock will not generate another DLM
	68	call. Userspace programs are assumed to handle their own local
	69	locking.
	70
fff9289b	71	Two levels of locks are supported - Shared Read, and Exclusive.
8df08c89 MF	72	Also supported is a Trylock operation.
	73
	74	For information on the libo2dlm interface, please see o2dlm.h,
	75	distributed with ocfs2-tools.
	76
	77	Lock value blocks can be read and written to a resource via read(2)
	78	and write(2) against the fd obtained via your open(2) call. The
	79	maximum currently supported LVB length is 64 bytes (though that is an
	80	OCFS2 DLM limitation). Through this mechanism, users of dlmfs can share
	81	small amounts of data amongst their nodes.
	82
	83	mkdir(2) signals dlmfs to join a domain (which will have the same name
	84	as the resulting directory)
	85
	86	rmdir(2) signals dlmfs to leave the domain
	87
	88	Locks for a given domain are represented by regular inodes inside the
	89	domain directory. Locking against them is done via the open(2) system
	90	call.
	91
	92	The open(2) call will not return until your lock has been granted or
	93	an error has occurred, unless it has been instructed to do a trylock
	94	operation. If the lock succeeds, you'll get an fd.
	95
	96	open(2) with O_CREAT to ensure the resource inode is created - dlmfs does
	97	not automatically create inodes for existing lock resources.
	98
	99	Open Flag Lock Request Type
	100	--------- -----------------
	101	O_RDONLY Shared Read
	102	O_RDWR Exclusive
	103
	104	Open Flag Resulting Locking Behavior
	105	--------- --------------------------
	106	O_NONBLOCK Trylock operation
	107
	108	You must provide exactly one of O_RDONLY or O_RDWR.
	109
	110	If O_NONBLOCK is also provided and the trylock operation was valid but
	111	could not lock the resource then open(2) will return ETXTBUSY.
	112
	113	close(2) drops the lock associated with your fd.
	114
	115	Modes passed to mkdir(2) or open(2) are adhered to locally. Chown is
	116	supported locally as well. This means you can use them to restrict
	117	access to the resources via dlmfs on your local node only.
	118
	119	The resource LVB may be read from the fd in either Shared Read or
	120	Exclusive modes via the read(2) system call. It can be written via
	121	write(2) only when open in Exclusive mode.
	122
	123	Once written, an LVB will be visible to other nodes who obtain Read
	124	Only or higher level locks on the resource.
	125
	126	See Also
	127	========
	128	http://opendlm.sourceforge.net/cvsmirror/opendlm/docs/dlmbook_final.pdf
	129
	130	For more information on the VMS distributed locking API.