<?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">
<!--
This file is autogenerated from hooks.html.in
Do not edit this file. Changes will be lost.
-->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<link rel="stylesheet" type="text/css" href="main.css" />
<link rel="SHORTCUT ICON" href="32favicon.png" />
<title>libvirt: Hooks for specific system management</title>
<meta name="description" content="libvirt, virtualization, virtualization API" />
</head>
<body>
<div id="header">
<div id="headerLogo"></div>
<div id="headerSearch">
<form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><div>
<input id="query" name="query" type="text" size="12" value="" />
<input id="submit" name="submit" type="submit" value="Search" />
</div></form>
</div>
</div>
<div id="body">
<div id="menu">
<ul class="l0"><li>
<div>
<a title="Front page of the libvirt website" class="inactive" href="index.html">Home</a>
</div>
</li><li>
<div>
<a title="Details of new features and bugs fixed in each release" class="inactive" href="news.html">News</a>
</div>
</li><li>
<div>
<a title="Get the latest source releases, binary builds and get access to the source repository" class="inactive" href="downloads.html">Downloads</a>
</div>
</li><li>
<div>
<a title="Information for users, administrators and developers" class="active" href="docs.html">Documentation</a>
<ul class="l1"><li>
<div>
<a title="Information about deploying and using libvirt" class="active" href="deployment.html">Deployment</a>
<ul class="l2"><li>
<div>
<a title="The URI formats used for connecting to libvirt" class="inactive" href="uri.html">URI format</a>
</div>
</li><li>
<div>
<a title="Enable remote access over TCP" class="inactive" href="remote.html">Remote access</a>
</div>
</li><li>
<div>
<a title="Configure authentication for the libvirt daemon" class="inactive" href="auth.html">Authentication</a>
</div>
</li><li>
<div>
<a title="Access the libvirt daemon from a native Windows client" class="inactive" href="windows.html">Windows port</a>
</div>
</li><li>
<div>
<a title="The library and the daemon logging support" class="inactive" href="logging.html">Logging</a>
</div>
</li><li>
<div>
<a title="Firewall and network filter configuration" class="inactive" href="firewall.html">Firewall</a>
</div>
</li><li>
<div>
<span class="active">Hooks</span>
</div>
</li></ul>
</div>
</li><li>
<div>
<a title="Overview of the logical subsystems in the libvirt API" class="inactive" href="intro.html">Architecture</a>
</div>
</li><li>
<div>
<a title="Description of the XML formats used in libvirt" class="inactive" href="format.html">XML format</a>
</div>
</li><li>
<div>
<a title="Hypervisor specific driver information" class="inactive" href="drivers.html">Drivers</a>
</div>
</li><li>
<div>
<a title="Reference manual for the C public API" class="inactive" href="html/index.html">API reference</a>
</div>
</li><li>
<div>
<a title="Bindings of the libvirt API for other languages" class="inactive" href="bindings.html">Language bindings</a>
</div>
</li><li>
<div>
<a title="Working on the internals of libvirt API, driver and daemon code" class="inactive" href="internals.html">Internals</a>
</div>
</li></ul>
</div>
</li><li>
<div>
<a title="User contributed content" class="inactive" href="http://wiki.libvirt.org">Wiki</a>
</div>
</li><li>
<div>
<a title="Frequently asked questions" class="inactive" href="http://wiki.libvirt.org/page/FAQ">FAQ</a>
</div>
</li><li>
<div>
<a title="How and where to report bugs and request features" class="inactive" href="bugs.html">Bug reports</a>
</div>
</li><li>
<div>
<a title="How to contact the developers via email and IRC" class="inactive" href="contact.html">Contact</a>
</div>
</li><li>
<div>
<a title="Miscellaneous links of interest related to libvirt" class="inactive" href="relatedlinks.html">Related Links</a>
</div>
</li><li>
<div>
<a title="Overview of all content on the website" class="inactive" href="sitemap.html">Sitemap</a>
</div>
</li></ul>
</div>
<div id="content">
<h1>Hooks for specific system management</h1>
<p>Libvirt includes synchronous hooks, starting from version 0.8.0, as a
way to tie in specific tailored system actions at a specific time.
If these scripts are present on the host where the hypervisor
is running, then they are called when the libvirt daemon is doingi
some significant action.</p>
<p>The scripts are expected to execute quickly, return a zero exit
status if all conditions are set for the daemon to continue the
action (non zero will be considered a failure which may
be ignored but in general will stop the ongoing operation).
The script also should not call back into libvirt as the daemon
is waiting for the script exit and deadlock is likely to occur.</p>
<p>The scripts are stored in the directory <code>/etc/libvirt/hooks/</code>
when using a standard installation path
(<code>$SYSCONF_DIR/libvirt/hooks/</code> in general).</p>
<p>Each script is given the following command line arguments:</p>
<ul><li> the first argument is the name of the object involved in the
operation, or '-' if there is none.
</li><li> the second argument is the name of the operation.
</li><li> the third argument is a suboperation indication like 'start' or
'end', or '-' if there is none.
</li><li> the last argument is an extra argument string or '-' if there
is none.
</li></ul>
<p>There are currently scripts for 3 domains of operation:
</p>
<ul><li><p><code>/etc/libvirt/hooks/daemon</code> script if
present is called at 3 points in time:</p>
<p>at daemon startup, typically started with the following
arguments:</p>
<pre>/etc/libvirt/hooks/daemon - start - start</pre>
<p>at daemon shutdown when it is about to exit, with the following
arguments:</p>
<pre>/etc/libvirt/hooks/daemon - shutdown - shutdown</pre>
<p>When the daemon is asked to reload its driver state when
receiving the SIGHUP signal, arguments are:</p>
<pre>/etc/libvirt/hooks/daemon - reload begin SIGHUP</pre>
</li><li><p><code>/etc/libvirt/hooks/qemu</code> script and <br /><code>/etc/libvirt/hooks/lxc</code> associate hooks for domain
operation on the respective QEmu/KVM and LXC drivers.</p>
<p> The domain related hooks also receive the full XML description
for the concerned domain on their stdin, which allows them to get
all the information from the domain, including UUID or storage
if that is needed for the script operation.</p>
<p> Currently only domain startup and domain end operations
involve the hook, the first one just before the domain gets
created.
For example if starting a QEmu domain named <code>test</code>
the following script will get called:</p>
<pre>/etc/libvirt/hooks/qemu test start begin -</pre>
<p> note that a non-zero return value from the script will abort the
domain startup operation, and if an error string is passed on
stderr by the hook script, it will be provided back to the user
at the libvirt API level.</p>
<p> For domain shutdown, the script will be called just after the
domain has finished execution, and the script will get:</p>
<pre>/etc/libvirt/hooks/qemu test stopped end -</pre>
<p> It is expected that other operations will be associated to hooks
but at the time of 0.8.0 only those 2 are associated to the
domains life cycle</p>
</li></ul>
<p></p>
</div>
</div>
<div id="footer">
<p id="sponsor">
Sponsored by:<br /><a href="http://et.redhat.com/"><img src="et.png" alt="Project sponsored by Red Hat Emerging Technology" /></a></p>
</div>
</body>
</html>
