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