Using Hooks 3.2

:!: Development version of OpenNebula 3.2. The material on this page needs to be reviewed for completeness and accuracy.

The Hook Manager present in OpenNebula enables the triggering of custom scripts tied to a change in state in a particular resource, being that a Host or a Virtual Machine. This opens a wide area of automation for system administrators to tailor their cloud infrastructures.

Configuration

Hook Manager configuration is set in /etc/one/oned.conf. Hooks can be tied to changes in host or virtual machine states, and they can be executed locally to the OpenNebula front-end and remotely in the relevant worker node.

In general, hook definition in /etc/one/oned.conf has two paremeters:

  • executable: path of the hook driver executable, can be an absolute path or relative to /usr/lib/one/mads
  • arguments: for the driver executable, can be an absolute path or relative to /etc/one/

Hooks for VirtualMachines

In the case of VirtualMachine hooks, the following can be defined:

  • name : for the hook, useful to track the hook (OPTIONAL)
  • on : when the hook should be executed,
    • CREATE, when the VM is created (onevm create)
    • RUNNING, after the VM is successfully booted
    • SHUTDOWN, after the VM is shutdown
    • STOP, after the VM is stopped (including VM image transfers)
    • DONE, after the VM is deleted or shutdown
    • FAILED, when the VM enters the failed state
  • command : path can be absolute or relative to /var/lib/one/remotes/hooks
  • arguments : for the hook. You can access the following VM attributes with $
    • $VMID, the ID of the VM that triggered the hook execution
    • $TEMPLATE, the template of the VM that triggered the hook, in xml and base64 encoded
  • remote : values,
    • YES, The hook is executed in the host where the VM was allocated
    • NO, The hook is executed in the OpenNebula server (default)

The following is an example of a hook tied to the DONE state of a VM:

<xterm> #——————————– Image Hook ———————————– # This hook is used to handle image saving and overwriting when virtual machines # reach the DONE state after being shutdown.

VM_HOOK = [ 

  name      = "image",
  on        = "DONE",
  command   = "image.rb",
  arguments = "$VMID" ]

#——————————————————————————- </xterm>

Hooks for Hosts

In the case of Host hooks, the following can be defined:

  • name : for the hook, useful to track the hook (OPTIONAL)
  • on : when the hook should be executed,
    • CREATE, when the Host is created (onehost create)
    • ERROR, when the Host enters the error state
    • DISABLE, when the Host is disabled
  • command : path can be absolute or relative to /var/lib/one/remotes/hooks
  • arguments : for the hook. You can use the following Host attributes with $
    • $HID, the ID of the Host that triggered the hook execution
    • $TEMPLATE, the full Host information, in xml and base64 encoded
  • remote : values,
    • YES, The hook is executed in the host
    • NO, The hook is executed in the OpenNebula server (default)

The following is an example of a hook tied to the ERROR state of a Host:

<xterm> #——————————– Host Hook ———————————– # This hook is used to perform recovery actions when a host fails. The VMs # running in the host can be deleted (use -d option) or resubmitted (-r) in # other host # Last argument (force) can be “y”, so suspended VMs in the host will be # resubmitted/deleted, or “n”, so suspended VMs in the host will be ignored

HOST_HOOK = [ 

  name      = "error",
  on        = "ERROR",
  command   = "host_error.rb",
  arguments = "$HID -r n",
  remote    = no ]

#——————————————————————————- </xterm>