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