[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

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" &gt;&amp;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

Attachment: signature.asc
Description: OpenPGP digital signature


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]