Re: [libvirt] [PATCH] docs: significant expansion of custom hook script information
On 08/05/2010 10:41 AM, Justin Clift wrote:
+
+ <h2><a name="location">Script Location</a></h2>
+ <p>The libvirt hook scripts are located in the directory
+ <code>$SYSCONF_DIR/etc/libvirt/hooks/</code>.
$SYSCONF_DIR == /etc in a distro, and == /usr/local/etc if you use the
default ./configure settings. Therefore, you should say that hooks live in:
$SYSCONF_DIR/libvirt/hooks/
+ <p>With Fedora and RHEL, this is
<code>/etc/libvirt/hooks/</code>.
At which point this sentence then makes sense.
+
+ <h2><a name="structure">Script structure</a></h2>
+ <p>The hook scripts are executed using standard Linux process creation
+ functions. Therefore, they must begin with the declaration of the
+ command interpreter to use.</p>
and have the chmod o+rx permissions.
+
+ <h2><a name="execution">Script execution</a></h2>
+ <ul>
+ <li>The "start" operation for the guest hook scripts, qemu and
lxc,
+ executes <b>prior</b> to the guest being created. This allows
the
+ guest start operation to be aborted if the script returns indicating
+ failure.<br/><br/></li>
+ <li>The "shutdown" operation for the guest hook scripts, qemu and
lxc,
+ executes <b>after</b> the guest has stopped. If the hook script
+ indicates failure in its return, the shut down of the guest cannot
+ be aborted because it has already been
performed.<br/><br/></li>
+ <li>Hook scripts execute in a synchronous fashion. Libvirt waits
+ for them to return before continuing the given
operation.<br/><br/>
+ This is most noticeable with the guest start operation, as a lengthy
+ operation in the hook script can mean an extended wait for the guest
+ to be available to end users.<br/><br/></li>
+ <li>For a hook script to be utilised, it have it's execute bit set
+ (ie. chmod +x <i>qemu</i>), and must be present when the libvirt
+ daemon is started.<br/><br/></li>
Ah, you did catch that, but in later text. Grammar:
s/it have it's/it must have its/
+ <h2><a name="return_codes">Return codes
and logging</a></h2>
+ <p>If a hook script returns with an exit code of 0, the libvirt daemon
+ regards this as successful and performs no logging of it.</p>
+ <p>However, if a hook script returns with a non zero exit code, the libvirt
+ daemon regards this as a failure, logs it with return code 256, and
+ additionally logs anything on stderr the hook script returns.</p>
Huh? Process exit status is < 256. Oh, I see - we're mistakenly
printing the raw process status code (a 16-bit number, where the upper 8
bits represent exit status if the lower 8 bits are all 0 and the process
exited normally, while the lower 8 bits represent what signal killed a
process if the process did not exit normally). We should fix the code
to use the WEXITSTATUS() macro and display the right exit status.
+ <p>For example, a hook script might use this code to
indicate failure,
+ and send a text string to stderr:</p>
+ <pre>echo "Could not find required XYZZY" >&2
+exit 1</pre>
+ <p>The resulting entry in the libvirt log will appear as:</p>
+ <pre>20:02:40.297: error : virHookCall:416 : Hook script execution failed:
Hook script /etc/libvirt/hooks/qemu qemu failed with error code 256:Could not find
required XYZZY</pre>
And once the code is fixed, this message would show an exit status of 1,
not 256.
--
Eric Blake eblake(a)redhat.com +1-801-349-2682
Libvirt virtualization library http://libvirt.org
Attachments:
- signature.asc (application/pgp-signature — 620 bytes)