mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 05:35:25 +00:00
docs: add page about virtlockd setup
Introduce some basic docs describing the virtlockd setup. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
This commit is contained in:
Daniel P. Berrange
parent
575c839b6e
commit
b4c7f7eaea
160
docs/locking-lockd.html.in
Normal file
160
docs/locking-lockd.html.in
Normal file
@ -0,0 +1,160 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<body>
|
||||
<h1>Virtual machine lock manager, virtlockd plugin</h1>
|
||||
|
||||
<ul id="toc"></ul>
|
||||
|
||||
<p>
|
||||
This page describes use of the <code>virtlockd</code>
|
||||
service as a <a href="locking.html">lock driver</a>
|
||||
plugin for virtual machine disk mutual exclusion.
|
||||
</p>
|
||||
|
||||
<h2><a name="background">virtlockd background</a></h2>
|
||||
|
||||
<p>
|
||||
The virtlockd daemon is a single purpose binary which
|
||||
focuses exclusively on the task of acquiring and holding
|
||||
locks on behalf of running virtual machines. It is
|
||||
designed to offer a low overhead, portable locking
|
||||
scheme can be used out of the box on virtualization
|
||||
hosts with minimal configuration overheads. It makes
|
||||
use of the POSIX fcntl advisory locking capability
|
||||
to hold locks, which is supported by the majority of
|
||||
commonly used filesystems.
|
||||
</p>
|
||||
|
||||
<h2><a name="sanlock">virtlockd daemon setup</a></h2>
|
||||
|
||||
<p>
|
||||
In most OS, the virtlockd daemon itself will not require
|
||||
any upfront configuration work. It is installed by default
|
||||
when libvirtd is present, and a systemd socket unit is
|
||||
registered such that the daemon will be automatically
|
||||
started when first required. With OS that predate systemd
|
||||
though, it will be necessary to start it at boot time,
|
||||
prior to libvirtd being started. On RHEL/Fedora distros,
|
||||
this can be achieved as follows
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
# chkconfig virtlockd on
|
||||
# service virtlockd start
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
The above instructions apply to the instance of virtlockd
|
||||
that runs privileged, and is used by the libvirtd daemon
|
||||
that runs privileged. If running libvirtd as an unprivileged
|
||||
user, it will always automatically spawn an instance of
|
||||
the virtlockd daemon unprivileged too. This requires no
|
||||
setup at all.
|
||||
</p>
|
||||
|
||||
<h2><a name="lockdplugin">libvirt lockd plugin configuration</a></h2>
|
||||
|
||||
<p>
|
||||
Once the virtlockd daemon is running, or setup to autostart,
|
||||
the next step is to configure the libvirt lockd plugin.
|
||||
There is a separate configuration file for each libvirt
|
||||
driver that is using virtlockd. For QEMU, we will edit
|
||||
<code>/etc/libvirt/qemu-lockd.conf</code>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The default behaviour of the lockd plugin is to acquire locks
|
||||
directly on the virtual disk images associated with the guest
|
||||
<disk> elements. This ensures it can run out of the box
|
||||
with no configuration, providing locking for disk images on
|
||||
shared filesystems such as NFS. It does not provide any cross
|
||||
host protection for storage that is backed by block devices,
|
||||
since locks acquired on device nodes in /dev only apply within
|
||||
the host. It may also be the case that the filesystem holding
|
||||
the disk images is not capable of supporting fcntl locks.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
To address these problems it is possible to tell lockd to
|
||||
acquire locks on an indirect file. Essentially lockd will
|
||||
calculate the SHA256 checksum of the fully qualified path,
|
||||
and create a zero length file in a given directory whose
|
||||
filename is the checksum. It will then acquire a lock on
|
||||
that file. Assuming the block devices assigned to the guest
|
||||
are using stable paths (eg /dev/disk/by-path/XXXXXXX) then
|
||||
this will allow for locks to apply across hosts. This
|
||||
feature can be enabled by setting a configuration setting
|
||||
that specifies the directory in which to create the lock
|
||||
files. The directory referred to should of course be
|
||||
placed on a shared filesystem (eg NFS) that is accessible
|
||||
to all hosts which can see the shared block devices.
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
$ su - root
|
||||
# augtool -s set \
|
||||
/files/etc/libvirt/qemu-lockd.conf/file_lockspace_dir \
|
||||
"/var/lib/libvirt/lockd/files"
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
If the guests are using either LVM and SCSI block devices
|
||||
for their virtual disks, there is a unique identifier
|
||||
associated with each device. It is possible to tell lockd
|
||||
to use this UUID as the basis for acquiring locks, rather
|
||||
than the SHA256 sum of the filename. The benefit of this
|
||||
is that the locking protection will work even if the file
|
||||
paths to the given block device are different on each
|
||||
host.
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
$ su - root
|
||||
# augtool -s set \
|
||||
/files/etc/libvirt/qemu-lockd.conf/scsi_lockspace_dir \
|
||||
"/var/lib/libvirt/lockd/scsi"
|
||||
# augtool -s set \
|
||||
/files/etc/libvirt/qemu-lockd.conf/lvm_lockspace_dir \
|
||||
"/var/lib/libvirt/lockd/lvm"
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
It is important to remember that the changes made to the
|
||||
<code>/etc/libvirt/qemu-lockd.conf</code> file must be
|
||||
propagated to all hosts before any virtual machines are
|
||||
launched on them. This ensures that all hosts are using
|
||||
the same locking mechanism
|
||||
</p>
|
||||
|
||||
<h2><a name="qemuconfig">QEMU/KVM driver configuration</a></h2>
|
||||
|
||||
<p>
|
||||
The QEMU driver is capable of using the virtlockd plugin
|
||||
since the release <span>1.0.2</span>.
|
||||
The out of the box configuration, however, currently
|
||||
uses the <strong>nop</strong> lock manager plugin.
|
||||
To get protection for disks, it is thus necessary
|
||||
to reconfigure QEMU to activate the <strong>lockd</strong>
|
||||
driver. This is achieved by editing the QEMU driver
|
||||
configuration file (<code>/etc/libvirt/qemu.conf</code>)
|
||||
and changing the <code>lock_manager</code> configuration
|
||||
tunable.
|
||||
</p>
|
||||
|
||||
<pre>
|
||||
$ su - root
|
||||
# augtool -s set /files/etc/libvirt/qemu.conf/lock_manager lockd
|
||||
# service libvirtd restart
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
Every time you start a guest, the virtlockd daemon will acquire
|
||||
locks on the disk files directly, or in one of the configured
|
||||
lookaside directories based on SHA256 sum. To check that locks
|
||||
are being acquired as expected, the <code>lslocks</code> tool
|
||||
can be run.
|
||||
</p>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@ -28,7 +28,7 @@
|
||||
nothing. This can be used if mutual exclusion between
|
||||
virtual machines is not required, or if it is being
|
||||
solved at another level in the management stack.</dd>
|
||||
<dt>lockd</dt>
|
||||
<dt><a href="locking-lockd.html">lockd</a></dt>
|
||||
<dd>This is the current preferred implementation shipped
|
||||
with libvirt. It uses the <code>virtlockd</code> daemon
|
||||
to manage locks using the POSIX fcntl() advisory locking
|
||||
|
||||
@ -102,6 +102,10 @@
|
||||
<a href="locking.html">Disk locking</a>
|
||||
<span>Ensuring exclusive guest access to disks</span>
|
||||
<ul>
|
||||
<li>
|
||||
<a href="locking-lockd.html">virtlockd</a>
|
||||
<span>virtlockd lock manager plugin</span>
|
||||
</li>
|
||||
<li>
|
||||
<a href="locking-sanlock.html">Sanlock</a>
|
||||
<span>Sanlock lock manager plugin</span>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user