0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. include:: <isonum.txt>
0003
0004 =====
0005 DLMFS
0006 =====
0007
0008 A minimal DLM userspace interface implemented via a virtual file
0009 system.
0010
0011 dlmfs is built with OCFS2 as it requires most of its infrastructure.
0012
0013 :Project web page: http://ocfs2.wiki.kernel.org
0014 :Tools web page: https://github.com/markfasheh/ocfs2-tools
0015 :OCFS2 mailing lists: https://oss.oracle.com/projects/ocfs2/mailman/
0016
0017 All code copyright 2005 Oracle except when otherwise noted.
0018
0019 Credits
0020 =======
0021
0022 Some code taken from ramfs which is Copyright |copy| 2000 Linus Torvalds
0023 and Transmeta Corp.
0024
0025 Mark Fasheh <mark.fasheh@oracle.com>
0026
0027 Caveats
0028 =======
0029 - Right now it only works with the OCFS2 DLM, though support for other
0030 DLM implementations should not be a major issue.
0031
0032 Mount options
0033 =============
0034 None
0035
0036 Usage
0037 =====
0038
0039 If you're just interested in OCFS2, then please see ocfs2.txt. The
0040 rest of this document will be geared towards those who want to use
0041 dlmfs for easy to setup and easy to use clustered locking in
0042 userspace.
0043
0044 Setup
0045 =====
0046
0047 dlmfs requires that the OCFS2 cluster infrastructure be in
0048 place. Please download ocfs2-tools from the above url and configure a
0049 cluster.
0050
0051 You'll want to start heartbeating on a volume which all the nodes in
0052 your lockspace can access. The easiest way to do this is via
0053 ocfs2_hb_ctl (distributed with ocfs2-tools). Right now it requires
0054 that an OCFS2 file system be in place so that it can automatically
0055 find its heartbeat area, though it will eventually support heartbeat
0056 against raw disks.
0057
0058 Please see the ocfs2_hb_ctl and mkfs.ocfs2 manual pages distributed
0059 with ocfs2-tools.
0060
0061 Once you're heartbeating, DLM lock 'domains' can be easily created /
0062 destroyed and locks within them accessed.
0063
0064 Locking
0065 =======
0066
0067 Users may access dlmfs via standard file system calls, or they can use
0068 'libo2dlm' (distributed with ocfs2-tools) which abstracts the file
0069 system calls and presents a more traditional locking api.
0070
0071 dlmfs handles lock caching automatically for the user, so a lock
0072 request for an already acquired lock will not generate another DLM
0073 call. Userspace programs are assumed to handle their own local
0074 locking.
0075
0076 Two levels of locks are supported - Shared Read, and Exclusive.
0077 Also supported is a Trylock operation.
0078
0079 For information on the libo2dlm interface, please see o2dlm.h,
0080 distributed with ocfs2-tools.
0081
0082 Lock value blocks can be read and written to a resource via read(2)
0083 and write(2) against the fd obtained via your open(2) call. The
0084 maximum currently supported LVB length is 64 bytes (though that is an
0085 OCFS2 DLM limitation). Through this mechanism, users of dlmfs can share
0086 small amounts of data amongst their nodes.
0087
0088 mkdir(2) signals dlmfs to join a domain (which will have the same name
0089 as the resulting directory)
0090
0091 rmdir(2) signals dlmfs to leave the domain
0092
0093 Locks for a given domain are represented by regular inodes inside the
0094 domain directory. Locking against them is done via the open(2) system
0095 call.
0096
0097 The open(2) call will not return until your lock has been granted or
0098 an error has occurred, unless it has been instructed to do a trylock
0099 operation. If the lock succeeds, you'll get an fd.
0100
0101 open(2) with O_CREAT to ensure the resource inode is created - dlmfs does
0102 not automatically create inodes for existing lock resources.
0103
0104 ============ ===========================
0105 Open Flag Lock Request Type
0106 ============ ===========================
0107 O_RDONLY Shared Read
0108 O_RDWR Exclusive
0109 ============ ===========================
0110
0111
0112 ============ ===========================
0113 Open Flag Resulting Locking Behavior
0114 ============ ===========================
0115 O_NONBLOCK Trylock operation
0116 ============ ===========================
0117
0118 You must provide exactly one of O_RDONLY or O_RDWR.
0119
0120 If O_NONBLOCK is also provided and the trylock operation was valid but
0121 could not lock the resource then open(2) will return ETXTBUSY.
0122
0123 close(2) drops the lock associated with your fd.
0124
0125 Modes passed to mkdir(2) or open(2) are adhered to locally. Chown is
0126 supported locally as well. This means you can use them to restrict
0127 access to the resources via dlmfs on your local node only.
0128
0129 The resource LVB may be read from the fd in either Shared Read or
0130 Exclusive modes via the read(2) system call. It can be written via
0131 write(2) only when open in Exclusive mode.
0132
0133 Once written, an LVB will be visible to other nodes who obtain Read
0134 Only or higher level locks on the resource.
0135
0136 See Also
0137 ========
0138 http://opendlm.sourceforge.net/cvsmirror/opendlm/docs/dlmbook_final.pdf
0139
0140 For more information on the VMS distributed locking API.
