Introduction

This page was started to encapsulate the results of reverse-engineering the as-installed Xen 4.1 /etc/xen/scripts/* scripts on Debian 7 Wheezy.

It assumes the xl toolkit is being used.

This page is published early – before extensive internal usage – because no similar information was found on the 'net.

How the scripts are called

Normally the scripts are called by xl (and thence libxenlight?) because they are named in /etc/xen/<DomU name>.cfg.

Structure of the scripts

The scripts are written in bash.

The scripts use a lot of common components: bash scripts which are sourced mostly to define functions.  For example, here is the start of the vif-bridge call tree.

    vif-bridge
    |
    +-- . /etc/xen/scripts/vif-common.sh
        |
        +-- . /etc/xen/scripts/xen-hotplug-common.sh
        |   |
        |   +-- . /etc/xen/scripts/hotplugpath.sh
        |   |
        |   +-- . /etc/xen/scripts/logging.sh
        |   |
        |   +-- . /etc/xen/scripts/xen-script-common.sh
        |   |
        |   +-- . /etc/xen/scripts/locking.sh
        |
        +-- . xen-network-common.sh
        |
        +-- findCommand
        |
        +-- evalVariables
        |

Developing the scripts

Run-time values

From vif-common.sh comments (Xen 4.1 version.  The "given by the Xend global configuration" is obsolete?):

Parameters may be read from the environment, the command line arguments, and the store, with overriding in that order. The environment is given by the driver, the command line is given by the Xend global configuration, and store details are given by the per-domain or per-device configuration.

Environment and arguments display

During development it may be convenient to run scripts other than by the normal mechanism, perhaps to run at a command prompt.  In that case the environment must be created and normal arguments passed.  A script's environment and arguments can be found by inserting this code at the beginning of a script:

log_fn=/tmp/${0##*/}.$$
exec >>$log_fn 2>&1
echo "env output: $(env)"
i=0
for arg in "$@"
do
    echo "Arg $((i++)): '$arg'"
done
unset i arg

That scrippet leaves stdout and stderr redirected to the log file.  Usually that is convenient.  In case it is not, the original redirections can be saved and restored:

exec 3>&1; exec 4>&2    # Save current redirections
log_fn=/tmp/${0##*/}.$$
exec >>$log_fn 2>&1
echo "env output: $(env)"
i=0
for arg in "$@"
do
    echo "Arg $((i++)): '$arg'"
done
unset i arg
exec >&3; exec 2>&4    # Restore original redirections
exec 3>&-; exec 4>&-   # Close temporary file descriptors 


Logging

Function log is available soon after a script initialises.  Normally it writes to /var/log/syslog.

log <level> <message>

<level> can be debug, info, warn, error or any of the other levels documented on the logger man page.

<message> can be multiple words.

Tracing

Normally bash tracing could be enabled by adding +x to the shebang line.  This did not work on Debian 7 Wheezy with Xen 4.1.

Using set -x in the scripts did work but stderr is sometimes discarded so it may be necessary to set up stderr redirection to log as described in the"Environment and arguments display" section above.

Why doesn't the script run?

Maybe it did run but failed with a syntax error which was not reported.  Running it at a command prompt would check the syntax.

Xen may require the script's full path in the configuration file.

Is the script executable?

Functions