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@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org