openkylin
/
libvirt
mirror of https://gitee.com/openkylin/libvirt.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity
libvirt/docs/internals/locking.html.in

268 lines
7.3 KiB
HTML
Raw Normal View History

Fix multiple formatting problems in HTML docs The rule generating the HTML docs passing the --html flag to xsltproc. This makes it use the legacy HTML parser, which either ignores or tries to fix all sorts of broken XML tags. There's no reason why we should be writing broken XML in the first place, so removing --html and adding the XHTML doctype to all files forces us to create good XML. This adds the XHTML doc type and fixes many, many XML tag problems it exposes. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-05-03 22:25:37 +08:00
<?xml version="1.0" encoding="UTF-8"?>
docs: switch to using HTML5 doctype declaration The HTML5 doctype is simply <!DOCTYPE html> no DTD is present because HTML5 is no longer defined as an extension of SGML. XSL has no way to natively output a doctype without a public or system identifier, so we have to use an <xsl:text> hack instead. See also https://dev.w3.org/html5/html-author/#doctype-declaration Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-27 01:01:25 +08:00
<!DOCTYPE html>
Fix multiple formatting problems in HTML docs The rule generating the HTML docs passing the --html flag to xsltproc. This makes it use the legacy HTML parser, which either ignores or tries to fix all sorts of broken XML tags. There's no reason why we should be writing broken XML in the first place, so removing --html and adding the XHTML doctype to all files forces us to create good XML. This adds the XHTML doc type and fixes many, many XML tag problems it exposes. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-05-03 22:25:37 +08:00
<html xmlns="http://www.w3.org/1999/xhtml">
Add initial docs about the lock managers
2010-11-23 00:44:13 +08:00
<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, to ensure exclusive
access to content.
</p>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 22:52:42 +08:00
<h2><a id="goals">Goals</a></h2>
Add initial docs about the lock managers
2010-11-23 00:44:13 +08:00
<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
maint: fix typos Our XML prefers "shareable" over "sharable". * docs/internals/locking.html.in: s/sharable/shareable/ * src/locking/lock_driver_sanlock.c (virLockManagerSanlockAddResource): Likewise.
2011-07-16 02:08:59 +08:00
disk is marked as shareable, or readonly). The scenarios
Add initial docs about the lock managers
2010-11-23 00:44:13 +08:00
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 a single machine.
</li>
</ol>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 22:52:42 +08:00
<h2><a id="requirement">Requirements</a></h2>
Add initial docs about the lock managers
2010-11-23 00:44:13 +08:00
<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 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>
<li>
Locks can be acquired for arbitrary VM related resources,
as determined by the management application.
</li>
</ol>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 22:52:42 +08:00
<h2><a id="design">Design</a></h2>
Add initial docs about the lock managers
2010-11-23 00:44:13 +08:00
<p>
Within a lock manager the following series of operations
will need to be supported.
</p>
<ul>
<li>
<strong>Register object</strong>
Register the identity of an object against which
locks will be acquired
</li>
<li>
<strong>Add resource</strong>
Associate a resource with an object for future
lock acquisition / release
</li>
<li>
<strong>Acquire locks</strong>
Acquire the locks for all resources associated
with the object
</li>
<li>
<strong>Release locks</strong>
Release the locks for all resources associated
with the object
</li>
<li>
<strong>Inquire locks</strong>
Get a representation of the state of the locks
for all resources associated with the object
</li>
</ul>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 22:52:42 +08:00
<h2><a id="impl">Plugin Implementations</a></h2>
Add initial docs about the lock managers
2010-11-23 00:44:13 +08:00
<p>
Lock manager implementations are provided as LGPLv2+
licensed, dlopen()able library modules. The plugins
will be loadable 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>
locking.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
#include &lt;libvirt/plugins/lock_manager.h&gt;
Add initial docs about the lock managers
2010-11-23 00:44:13 +08:00
</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>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 22:52:42 +08:00
<h2><a id="qemuIntegrate">QEMU Driver integration</a></h2>
Add initial docs about the lock managers
2010-11-23 00:44:13 +08:00
<p>
With the QEMU driver, the lock plugin will be set
in the <code>/etc/libvirt/qemu.conf</code> configuration
file by specifying the lock manager name.
</p>
<pre>
locking.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
lockManager="sanlock"
Add initial docs about the lock managers
2010-11-23 00:44:13 +08:00
</pre>
<p>
By default the lock manager will be a 'no op' implementation
for backwards compatibility
</p>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 22:52:42 +08:00
<h2><a id="usagePatterns">Lock usage patterns</a></h2>
Add initial docs about the lock managers
2010-11-23 00:44:13 +08:00
<p>
Various typos and misspellings
2012-10-12 00:31:20 +08:00
The following pseudo code illustrates the common
Add initial docs about the lock managers
2010-11-23 00:44:13 +08:00
patterns of operations invoked on the lock
manager plugin callbacks.
</p>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 22:52:42 +08:00
<h3><a id="usageLockAcquire">Lock acquisition</a></h3>
Add initial docs about the lock managers
2010-11-23 00:44:13 +08:00
<p>
Initial lock acquisition will be performed from the
process that is to own the lock. This is typically
the QEMU child process, in between the fork+exec
pairing. When adding further resources on the fly,
to an existing object holding locks, this will be
done from the libvirtd process.
</p>
<pre>
locking.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
virLockManagerParam params[] = {
{ .type = VIR_LOCK_MANAGER_PARAM_TYPE_UUID,
.key = "uuid",
},
{ .type = VIR_LOCK_MANAGER_PARAM_TYPE_STRING,
.key = "name",
.value = { .str = dom->def->name },
},
{ .type = VIR_LOCK_MANAGER_PARAM_TYPE_UINT,
.key = "id",
.value = { .i = dom->def->id },
},
{ .type = VIR_LOCK_MANAGER_PARAM_TYPE_UINT,
.key = "pid",
.value = { .i = dom->pid },
},
{ .type = VIR_LOCK_MANAGER_PARAM_TYPE_CSTRING,
.key = "uri",
.value = { .cstr = driver->uri },
},
};
mgr = virLockManagerNew(lockPlugin,
VIR_LOCK_MANAGER_TYPE_DOMAIN,
ARRAY_CARDINALITY(params),
params,
0)));
foreach (initial disks)
virLockManagerAddResource(mgr,
VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK,
$path, 0, NULL, $flags);
if (virLockManagerAcquire(lock, NULL, 0) &lt; 0);
...abort...
Add initial docs about the lock managers
2010-11-23 00:44:13 +08:00
</pre>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 22:52:42 +08:00
<h3><a id="usageLockAttach">Lock release</a></h3>
Add initial docs about the lock managers
2010-11-23 00:44:13 +08:00
<p>
The locks are all implicitly released when the process
that acquired them exits, however, a process may
voluntarily give up the lock by running
</p>
<pre>
locking.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
char *state = NULL;
virLockManagerParam params[] = {
{ .type = VIR_LOCK_MANAGER_PARAM_TYPE_UUID,
.key = "uuid",
},
{ .type = VIR_LOCK_MANAGER_PARAM_TYPE_STRING,
.key = "name",
.value = { .str = dom->def->name },
},
{ .type = VIR_LOCK_MANAGER_PARAM_TYPE_UINT,
.key = "id",
.value = { .i = dom->def->id },
},
{ .type = VIR_LOCK_MANAGER_PARAM_TYPE_UINT,
.key = "pid",
.value = { .i = dom->pid },
},
{ .type = VIR_LOCK_MANAGER_PARAM_TYPE_CSTRING,
.key = "uri",
.value = { .cstr = driver->uri },
},
};
mgr = virLockManagerNew(lockPlugin,
VIR_LOCK_MANAGER_TYPE_DOMAIN,
ARRAY_CARDINALITY(params),
params,
0)));
foreach (initial disks)
virLockManagerAddResource(mgr,
VIR_LOCK_MANAGER_RESOURCE_TYPE_DISK,
$path, 0, NULL, $flags);
virLockManagerRelease(mgr, &amp; state, 0);
Add initial docs about the lock managers
2010-11-23 00:44:13 +08:00
</pre>
<p>
The returned state string can be passed to the
<code>virLockManagerAcquire</code> method to
later re-acquire the exact same locks. This
state transfer is commonly used when performing
live migration of virtual machines. By validating
the state the lock manager can ensure no other
VM has re-acquire the same locks on a different
host. The state can also be obtained without
releasing the locks, by calling the
<code>virLockManagerInquire</code> method.
</p>
</body>
</html>