dlmfs.rst 4.4 KB

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