114a19fa5SMauro Carvalho Chehab.. SPDX-License-Identifier: GPL-2.0 214a19fa5SMauro Carvalho Chehab.. include:: <isonum.txt> 314a19fa5SMauro Carvalho Chehab 414a19fa5SMauro Carvalho Chehab===== 514a19fa5SMauro Carvalho ChehabDLMFS 614a19fa5SMauro Carvalho Chehab===== 714a19fa5SMauro Carvalho Chehab 814a19fa5SMauro Carvalho ChehabA minimal DLM userspace interface implemented via a virtual file 914a19fa5SMauro Carvalho Chehabsystem. 1014a19fa5SMauro Carvalho Chehab 1114a19fa5SMauro Carvalho Chehabdlmfs is built with OCFS2 as it requires most of its infrastructure. 1214a19fa5SMauro Carvalho Chehab 1314a19fa5SMauro Carvalho Chehab:Project web page: http://ocfs2.wiki.kernel.org 1414a19fa5SMauro Carvalho Chehab:Tools web page: https://github.com/markfasheh/ocfs2-tools 15*5a569db6SAnthony Iliopoulos:OCFS2 mailing lists: https://subspace.kernel.org/lists.linux.dev.html 1614a19fa5SMauro Carvalho Chehab 1714a19fa5SMauro Carvalho ChehabAll code copyright 2005 Oracle except when otherwise noted. 1814a19fa5SMauro Carvalho Chehab 1914a19fa5SMauro Carvalho ChehabCredits 2014a19fa5SMauro Carvalho Chehab======= 2114a19fa5SMauro Carvalho Chehab 2214a19fa5SMauro Carvalho ChehabSome code taken from ramfs which is Copyright |copy| 2000 Linus Torvalds 2314a19fa5SMauro Carvalho Chehaband Transmeta Corp. 2414a19fa5SMauro Carvalho Chehab 2514a19fa5SMauro Carvalho ChehabMark Fasheh <mark.fasheh@oracle.com> 2614a19fa5SMauro Carvalho Chehab 2714a19fa5SMauro Carvalho ChehabCaveats 2814a19fa5SMauro Carvalho Chehab======= 2914a19fa5SMauro Carvalho Chehab- Right now it only works with the OCFS2 DLM, though support for other 3014a19fa5SMauro Carvalho Chehab DLM implementations should not be a major issue. 3114a19fa5SMauro Carvalho Chehab 3214a19fa5SMauro Carvalho ChehabMount options 3314a19fa5SMauro Carvalho Chehab============= 3414a19fa5SMauro Carvalho ChehabNone 3514a19fa5SMauro Carvalho Chehab 3614a19fa5SMauro Carvalho ChehabUsage 3714a19fa5SMauro Carvalho Chehab===== 3814a19fa5SMauro Carvalho Chehab 3914a19fa5SMauro Carvalho ChehabIf you're just interested in OCFS2, then please see ocfs2.txt. The 4014a19fa5SMauro Carvalho Chehabrest of this document will be geared towards those who want to use 4114a19fa5SMauro Carvalho Chehabdlmfs for easy to setup and easy to use clustered locking in 4214a19fa5SMauro Carvalho Chehabuserspace. 4314a19fa5SMauro Carvalho Chehab 4414a19fa5SMauro Carvalho ChehabSetup 4514a19fa5SMauro Carvalho Chehab===== 4614a19fa5SMauro Carvalho Chehab 4714a19fa5SMauro Carvalho Chehabdlmfs requires that the OCFS2 cluster infrastructure be in 4814a19fa5SMauro Carvalho Chehabplace. Please download ocfs2-tools from the above url and configure a 4914a19fa5SMauro Carvalho Chehabcluster. 5014a19fa5SMauro Carvalho Chehab 5114a19fa5SMauro Carvalho ChehabYou'll want to start heartbeating on a volume which all the nodes in 5214a19fa5SMauro Carvalho Chehabyour lockspace can access. The easiest way to do this is via 5314a19fa5SMauro Carvalho Chehabocfs2_hb_ctl (distributed with ocfs2-tools). Right now it requires 5414a19fa5SMauro Carvalho Chehabthat an OCFS2 file system be in place so that it can automatically 5514a19fa5SMauro Carvalho Chehabfind its heartbeat area, though it will eventually support heartbeat 5614a19fa5SMauro Carvalho Chehabagainst raw disks. 5714a19fa5SMauro Carvalho Chehab 5814a19fa5SMauro Carvalho ChehabPlease see the ocfs2_hb_ctl and mkfs.ocfs2 manual pages distributed 5914a19fa5SMauro Carvalho Chehabwith ocfs2-tools. 6014a19fa5SMauro Carvalho Chehab 6114a19fa5SMauro Carvalho ChehabOnce you're heartbeating, DLM lock 'domains' can be easily created / 6214a19fa5SMauro Carvalho Chehabdestroyed and locks within them accessed. 6314a19fa5SMauro Carvalho Chehab 6414a19fa5SMauro Carvalho ChehabLocking 6514a19fa5SMauro Carvalho Chehab======= 6614a19fa5SMauro Carvalho Chehab 6714a19fa5SMauro Carvalho ChehabUsers may access dlmfs via standard file system calls, or they can use 6814a19fa5SMauro Carvalho Chehab'libo2dlm' (distributed with ocfs2-tools) which abstracts the file 6914a19fa5SMauro Carvalho Chehabsystem calls and presents a more traditional locking api. 7014a19fa5SMauro Carvalho Chehab 7114a19fa5SMauro Carvalho Chehabdlmfs handles lock caching automatically for the user, so a lock 7214a19fa5SMauro Carvalho Chehabrequest for an already acquired lock will not generate another DLM 7314a19fa5SMauro Carvalho Chehabcall. Userspace programs are assumed to handle their own local 7414a19fa5SMauro Carvalho Chehablocking. 7514a19fa5SMauro Carvalho Chehab 7614a19fa5SMauro Carvalho ChehabTwo levels of locks are supported - Shared Read, and Exclusive. 7714a19fa5SMauro Carvalho ChehabAlso supported is a Trylock operation. 7814a19fa5SMauro Carvalho Chehab 7914a19fa5SMauro Carvalho ChehabFor information on the libo2dlm interface, please see o2dlm.h, 8014a19fa5SMauro Carvalho Chehabdistributed with ocfs2-tools. 8114a19fa5SMauro Carvalho Chehab 8214a19fa5SMauro Carvalho ChehabLock value blocks can be read and written to a resource via read(2) 8314a19fa5SMauro Carvalho Chehaband write(2) against the fd obtained via your open(2) call. The 8414a19fa5SMauro Carvalho Chehabmaximum currently supported LVB length is 64 bytes (though that is an 8514a19fa5SMauro Carvalho ChehabOCFS2 DLM limitation). Through this mechanism, users of dlmfs can share 8614a19fa5SMauro Carvalho Chehabsmall amounts of data amongst their nodes. 8714a19fa5SMauro Carvalho Chehab 8814a19fa5SMauro Carvalho Chehabmkdir(2) signals dlmfs to join a domain (which will have the same name 8914a19fa5SMauro Carvalho Chehabas the resulting directory) 9014a19fa5SMauro Carvalho Chehab 9114a19fa5SMauro Carvalho Chehabrmdir(2) signals dlmfs to leave the domain 9214a19fa5SMauro Carvalho Chehab 9314a19fa5SMauro Carvalho ChehabLocks for a given domain are represented by regular inodes inside the 9414a19fa5SMauro Carvalho Chehabdomain directory. Locking against them is done via the open(2) system 9514a19fa5SMauro Carvalho Chehabcall. 9614a19fa5SMauro Carvalho Chehab 9714a19fa5SMauro Carvalho ChehabThe open(2) call will not return until your lock has been granted or 9814a19fa5SMauro Carvalho Chehaban error has occurred, unless it has been instructed to do a trylock 9914a19fa5SMauro Carvalho Chehaboperation. If the lock succeeds, you'll get an fd. 10014a19fa5SMauro Carvalho Chehab 10114a19fa5SMauro Carvalho Chehabopen(2) with O_CREAT to ensure the resource inode is created - dlmfs does 10214a19fa5SMauro Carvalho Chehabnot automatically create inodes for existing lock resources. 10314a19fa5SMauro Carvalho Chehab 10414a19fa5SMauro Carvalho Chehab============ =========================== 10514a19fa5SMauro Carvalho ChehabOpen Flag Lock Request Type 10614a19fa5SMauro Carvalho Chehab============ =========================== 10714a19fa5SMauro Carvalho ChehabO_RDONLY Shared Read 10814a19fa5SMauro Carvalho ChehabO_RDWR Exclusive 10914a19fa5SMauro Carvalho Chehab============ =========================== 11014a19fa5SMauro Carvalho Chehab 11114a19fa5SMauro Carvalho Chehab 11214a19fa5SMauro Carvalho Chehab============ =========================== 11314a19fa5SMauro Carvalho ChehabOpen Flag Resulting Locking Behavior 11414a19fa5SMauro Carvalho Chehab============ =========================== 11514a19fa5SMauro Carvalho ChehabO_NONBLOCK Trylock operation 11614a19fa5SMauro Carvalho Chehab============ =========================== 11714a19fa5SMauro Carvalho Chehab 11814a19fa5SMauro Carvalho ChehabYou must provide exactly one of O_RDONLY or O_RDWR. 11914a19fa5SMauro Carvalho Chehab 12014a19fa5SMauro Carvalho ChehabIf O_NONBLOCK is also provided and the trylock operation was valid but 12114a19fa5SMauro Carvalho Chehabcould not lock the resource then open(2) will return ETXTBUSY. 12214a19fa5SMauro Carvalho Chehab 12314a19fa5SMauro Carvalho Chehabclose(2) drops the lock associated with your fd. 12414a19fa5SMauro Carvalho Chehab 12514a19fa5SMauro Carvalho ChehabModes passed to mkdir(2) or open(2) are adhered to locally. Chown is 12614a19fa5SMauro Carvalho Chehabsupported locally as well. This means you can use them to restrict 12714a19fa5SMauro Carvalho Chehabaccess to the resources via dlmfs on your local node only. 12814a19fa5SMauro Carvalho Chehab 12914a19fa5SMauro Carvalho ChehabThe resource LVB may be read from the fd in either Shared Read or 13014a19fa5SMauro Carvalho ChehabExclusive modes via the read(2) system call. It can be written via 13114a19fa5SMauro Carvalho Chehabwrite(2) only when open in Exclusive mode. 13214a19fa5SMauro Carvalho Chehab 13314a19fa5SMauro Carvalho ChehabOnce written, an LVB will be visible to other nodes who obtain Read 13414a19fa5SMauro Carvalho ChehabOnly or higher level locks on the resource. 13514a19fa5SMauro Carvalho Chehab 13614a19fa5SMauro Carvalho ChehabSee Also 13714a19fa5SMauro Carvalho Chehab======== 13814a19fa5SMauro Carvalho Chehabhttp://opendlm.sourceforge.net/cvsmirror/opendlm/docs/dlmbook_final.pdf 13914a19fa5SMauro Carvalho Chehab 14014a19fa5SMauro Carvalho ChehabFor more information on the VMS distributed locking API. 141