[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[libvirt] [PATCH 8/8] Add initial docs about the lock managers



---
 docs/internals-locking.html.in |  301 ++++++++++++++++++++++++++++++++++++++++
 1 files changed, 301 insertions(+), 0 deletions(-)
 create mode 100644 docs/internals-locking.html.in

diff --git a/docs/internals-locking.html.in b/docs/internals-locking.html.in
new file mode 100644
index 0000000..90054f0
--- /dev/null
+++ b/docs/internals-locking.html.in
@@ -0,0 +1,301 @@
+<html>
+  <body>
+    <h1>Resource Lock Manager</h1>
+
+    <ul id="toc"></ul>
+
+    <p>
+      This page describes the design of the resource lock manager
+      that is used for locking disk images with the QEMU driver.
+    </p>
+
+    <h2><a name="goals">Goals</a></h2>
+
+    <p>
+      The high level goal is to prevent the same disk image being
+      used by more than one QEMU instance at a time (unless the
+      disk is marked as sharable, or readonly). The scenarios
+      to be prevented are thus:
+    </p>
+
+    <ol>
+      <li>
+	Two different guests running configured to point at the
+	same disk image.
+      </li>
+      <li>
+	One guest being started more than once on two different
+	machines due to admin mistake
+      </li>
+      <li>
+	One guest being started more than once on a single machine
+	due to libvirt driver bug on aa single machine.
+      </li>
+    </ol>
+
+    <h2><a name="requirement">Requirements</a></h2>
+
+    <p>
+      The high level goal leads to a set of requirements
+      for the lock manager design
+    </p>
+
+    <ol>
+      <li>
+	A lock must be held on a disk whenever a QEMU process
+	has the disk open
+      </li>
+      <li>
+	The lock scheme must allow QEMU to be configured with
+	readonly, shared write, or exclusive writable disks
+      </li>
+      <li>
+	A lock must be held on a disk whenever libvirtd makes
+	changes to user/group ownership and SELinux labelling.
+      </li>
+      <li>
+	At least one locking impl must allow use of libvirtd on
+	a single host without any admin config tasks
+      </li>
+      <li>
+	A lock handover must be performed during the migration
+	process where 2 QEMU processes will have the same disk
+	open concurrently.
+      </li>
+      <li>
+	The lock manager must be able to identify and kill the
+	process accessing the resource if the lock is revoked.
+      </li>
+    </ol>
+
+    <h2><a name="design">Design</a></h2>
+
+    <p>
+      The requirements call for a design with two distinct lockspaces:
+    </p>
+
+    <ol>
+      <li>
+	The <strong>primary lockspace</strong> is used to protect the content of
+	disk images. This will honour the disk sharing modes to
+	allow readonly/shared disk to be assigned to multiple
+	guests concurrently.
+      </li>
+      <li>
+	The <strong>secondary lockspace</strong> is used to protect the metadata
+	of disk images. This lock will be held whenever file
+	permissions / ownership / attributes are changed, and
+	is always exclusive, regardless of sharing mode. The
+	primary lock will be held prior to obtaining the secondary
+	lock.
+      </li>
+    </ol>
+
+    <p>
+      Within each lockspace the following operations will need to be
+      supported
+    </p>
+
+    <ul>
+      <li>
+	<strong>Acquire object lock</strong>
+	Acquire locks on all resources initially
+	registered against an object
+      </li>
+      <li>
+	<strong>Release object lock</strong>
+	Release locks on all resources currently
+	registered against an object
+      </li>
+      <li>
+	<strong>Associate object lock</strong>
+	Associate the current process with an existing
+	set of locks for an object
+      </li>
+      <li>
+	<strong>Deassociate object lock</strong>
+	Deassociate the current process with an
+	existing set of locks for an object.
+      </li>
+      <li>
+	<strong>Register resource</strong>
+	Register an initial resource against an object
+      </li>
+      <li>
+	<strong>Get object lock state</strong>
+	Obtain an representation of the current object
+	lock state.
+      </li>
+      <li>
+	<strong>Acquire a resource lock</strong>
+	Register and acquire a lock for a resource
+	to be added to a locked object.
+      </li>
+      <li>
+	<strong>Release a resource lock</strong>
+	Dereigster and release a lock for a resource
+	to be removed from a lock object
+      </li>
+    </ul>
+
+    <h2><a name="impl">Plugin Implementations</a></h2>
+
+    <p>
+      Lock manager implementations are provided as LGPLv2+
+      licensed, dlopen()able library modules. A different
+      lock manager implementation may be used
+      for the primary and secondary lockspaces. With the
+      QEMU driver, these can be configured via the
+      <code>/etc/libvirt/qemu.conf</code> configuration
+      file by specifying the lock manager name.
+    </p>
+
+    <pre>
+      contentLockManager="fcntl"
+      metadataLockManager="fcntl"
+    </pre>
+
+    <p>
+      Lock manager implmentations are free to support
+      both content and metadata locks, however, if the
+      plugin author is only able to handle one lockspace,
+      the other can be delegated to the standard fcntl
+      lock manager. The QEMU driver will load the lock
+      manager plugin binaries from the following location
+    </p>
+
+    <pre>
+/usr/{lib,lib64}/libvirt/lock_manager/$NAME.so
+</pre>
+
+    <p>
+      The lock manager plugin must export a single ELF
+      symbol named <code>virLockDriverImpl</code>, which is
+      a static instance of the <code>virLockDriver</code>
+      struct. The struct is defined in the header file
+    </p>
+
+    <pre>
+      #include &lt;libvirt/plugins/lock_manager.h&gt;
+    </pre>
+
+    <p>
+      All callbacks in the struct must be initialized
+      to non-NULL pointers. The semantics of each
+      callback are defined in the API docs embedded
+      in the previously mentioned header file
+    </p>
+
+    <h2><a name="usagePatterns">Lock usage patterns</a></h2>
+
+    <p>
+      The following psuedo code illustrates the common
+      patterns of operations invoked on the lock
+      manager plugin callbacks.
+    </p>
+
+    <h3><a name="usageLockAcquire">Lock acquisition</a></h3>
+
+    <p>
+      Lock acquisition will always be performed from the
+      process that is to own the lock. This is typically
+      the QEMU child process, in between the fork+exec
+      pairing, but it may occassionally be held directly
+      by libvirtd.
+    </p>
+
+    <pre>
+      mgr = virLockManagerNew(lockPlugin,
+                              VIR_LOCK_MANAGER_MODE_CONTENT,
+                              VIR_LOCK_MANAGER_TYPE_DOMAIN);
+      virLockManagerSetParameter(mgr, "uuid", $uuid);
+      virLockManagerSetParameter(mgr, "name", $name);
+
+      foreach (initial disks)
+          virLockManagerAddResource(mgr,
+                                    VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK,
+                                    $path, $flags);
+
+      if (virLockManagerAcquireObject(mgr) &lt; 0)
+        ...abort...
+    </pre>
+
+    <p>
+      The lock is implicitly released when the process
+      that acquired it exits, however, a process may
+      voluntarily give up the lock by running
+    </p>
+
+    <pre>
+      virLockManagerReleaseObject(mgr);
+    </pre>
+
+    <h3><a name="usageLockAttach">Lock attachment</a></h3>
+
+    <p>
+      Any time a process needs todo work on behalf of
+      another process that holds a lock, it will associate
+      itself with the existing lock. This sequence is
+      identical to the previous one, except for the
+      last step.
+    </p>
+
+
+    <pre>
+      mgr = virLockManagerNew(contentLock,
+                              VIR_LOCK_MANAGER_MODE_CONTENT,
+                              VIR_LOCK_MANAGER_TYPE_DOMAIN);
+      virLockManagerSetParameter(mgr, "uuid", $uuid);
+      virLockManagerSetParameter(mgr, "name", $name);
+
+      foreach (current disks)
+          virLockManagerAddResource(mgr,
+                                    VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK,
+                                    $path, $flags);
+
+      if (virLockManagerAttachObject(mgr, $pid) &lt; 0)
+        ...abort...
+    </pre>
+
+    <p>
+      A lock association will always be explicitly broken
+      by running
+    </p>
+
+    <pre>
+      virLockManagerDetachObject(mgr, $pid);
+    </pre>
+
+
+    <h3><a name="usageLiveResourceChange">Live resource changes</a></h3>
+
+    <p>
+      When adding a resource to an existing locked object (eg to
+      hotplug a disk into a VM), the lock manager will first
+      attach to the locked object, acquire a lock on the
+      new resource, then detach from the locked object.
+    </p>
+
+    <pre>
+      ... initial glue ...
+      if (virLockManagerAttachObject(mgr, $pid) &lt; 0)
+        ...abort...
+
+      if (virLockManagerAcquireResource(mgr,
+                                        VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK,
+                                        $path, $flags) &lt; 0)
+        ...abort...
+
+      ...assign resource to object
+
+      virLockManagerDetachObject(mgr, $pid)
+    </pre>
+
+    <p>
+      Removing a resource from an existing object is an identical
+      process, but with <code>virLockManagerReleaseResource</code>
+      invoked instead
+    </p>
+
+  </body>
+</html>
-- 
1.7.2.3


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]