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