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