This page details how you can add custom scripts that run on specified hooks during the VM build process.

Note that the build hooks run during the VM build process. See initconf hooks for hooks that run once the VM has been deployed and booted.

As examples, you may wish to use build hooks to:

  • install a particular RPM package using yum

  • create or copy additional files required by your Rhino application into place

  • set suitable configuration (profiles, resource adaptor attributes, SAS bundle mappings, etc) for your Rhino application in preparation for its first-time startup.

Note If using yum install to download and install a specific package in a build script, make sure you specify the -y flag for automatic confirmation. E.g. sudo yum install -y vim.

Available build hooks

As an overview of the build process:

  • firstly, a Dockerfile containing instructions for all components of the VM is assembled and built

  • secondly, the container boots in order to run "live" installation steps such as starting Rhino for the first time

  • thirdly, the container is shut down and committed to a disk image

  • finally, the disk image is converted to VM image(s) of the requested format(s).

All hooks run during the "live" phase, as described below. As such, the hooks have full access to the VM-to-be’s filesystem.

Build hook name Point hook is run

before-rhino-install

This is the first build hook that will run. This hook will run immediately prior to installing Rhino.

NB. The RHINO_HOME and CLIENT_HOME environment variables are not defined for this hook, as Rhino has not yet been installed.

after-rhino-install

This hook will run after Rhino is installed, but before it is started.

after-rhino-import

This hook will run after Rhino is started and your Rhino export, Sentinel package, or deployable units (see Preparing your application) have been loaded into the Rhino SLEE. When this hook runs, Rhino is running and the SLEE is in the Started state. If you provided a SAS bundle mappings file, the mappings will have been set in Rhino by this point.

final

This hook will run at the very end of the "live" install phase. Rhino will no longer be running.

Registering build hook scripts

To register scripts to run against build hooks, create executables named after each build hook you want to run against. Create a ZIP archive of these executables named custom-build.zip, then place that archive in the same directory as the Rhino license file when running the VM Build Container.

Note Each script’s name must match the corresponding hook’s name exactly. In particular, note that the names use hyphens (-), not underscores (_).
Note Ensure that the scripts have the user-executable permission bit set.
Note Ensure that the scripts' filenames have no extension, e.g. just before-rhino-install, not before-rhino-install.sh.

The build scripts must be in the root of the custom-build.zip archive, i.e. they must appear in the current working directory when the archive is extracted. The custom-build.zip archive may contain additional supplementary data for your build scripts alongside the executables. This data can take the form of any number of directories and files in any structure; all that matters is that the executable hook scripts are in the root directory. Build scripts can call other programs to achieve their tasks; these must already exist on the VMs or be provided in the custom-build.zip archive.

Example custom-build.zip archive structure:

custom-build.zip
├── before-rhino-install
├── after-rhino-import
├── required-os-package.rpm
└── application-files
    └── application-config.properties

How build hook scripts are run

Before any build hook scripts are run, the custom-build.zip file will be extracted to the directory /home/<username>/install/build-hooks/workspace. This is part of the following directory structure:

/home/<username>/install/build-hooks
├── workspace
├── output

All build hook scripts are run as the default user. They are given no command-line parameters and the current working directory will be set to the above workspace directory, meaning the script will be able to find the entire contents of the custom-build.zip file in the current working directory.

When a build hook script is run, any output to the stdout and stderr streams will be captured and this output will be stored in a file in the output directory.

  • The output file for a build hook script will be named the same as the build hook script but with a .out extension added, e.g. The file containing output for the before-rhino-install build hook will be named before-rhino-install.out.

  • An empty file will be created if a build hook script does not write to either stdout or stderr.

  • No output files will be created for build hooks that do not have scripts registered against them.

If a build hook script returns with any return code other than 0, this will be interpreted as a failure and will cause the VM build process to be immediately aborted.

If the build succeeds, the workspace directory is cleaned up, but the original executable scripts will be available on the VM in the scripts directory, and the output directory is left in place. For example, if the before-rhino-install and after-rhino-import hooks were included in the custom-build.zip file, then the VM’s filesystem will include the following:

/home/<username>/install/build-hooks
├── scripts
    ├── before-rhino-install
    ├── after-rhino-import
├── output
    ├── before-rhino-install.out
    ├── after-rhino-import.out

In addition, regardless of whether the build succeeded or failed, the .out files from the build hooks will be made available outside the VMBC in the target directory. See Output files.

Environment variables

When a build hook script runs, the following variables are present in its environment.

  • The environment variable JAVA_HOME is set to the location of the Java Runtime Environment (JRE) that comes installed on the VM.

  • Additionally, for all hooks except before-rhino-install, the RHINO_HOME and CLIENT_HOME environment variables are set.

    • RHINO_HOME points to the location of the Rhino installation.

    • CLIENT_HOME points to the client directory within the Rhino installation, inside which you can find various Rhino tools, most notably ${CLIENT_HOME}/bin/rhino-console.

Caveats when using build hooks

There are some actions that might have some unexpected effects. These include:

  • Editing the network-related files /etc/hosts and /etc/resolv.conf. VMBC uses Docker during the build process, and Docker overrides /etc/hosts and /etc/resolv.conf as part of its internal networking. Therefore, these files cannot be edited during build hooks. Any required changes should be applied at deployment time through the Initconf hooks instead.

  • Editing files and configuration stored in the node subdirectory. During the image build process, VMBC temporarily creates a node with node ID 101. This node gets deleted at the end of the build process. The user specifies, in the custom-vm-pool.yaml file, node IDs for each VM and initconf on each VM creates a node with the configured ID when the VM is deployed. This means that any changes to files or configuration, stored in the directory for the temporary node with ID 101, will not persist. Such changes should instead by applied to the default configuration in etc/defaults, or be done at deployment time through the Initconf hooks instead. Examples of configuration that is stored in the node subdirectory includes:

    • Logging and Tracer configuration (either set through rhino-console or by editing config/logging.xml directly)

    • Rhino configuration in config/rhino-config.xml

    • Savanna cluster configuration in config/savanna

    • MLet configuration in config/permachine-mlet.conf

    • specific files required by resource adaptors, e.g. config/tcapsim-gt-table.txt.

  • Updating system packages through yum during a build hook. It is strongly recommended not to update any of the pre-installed system packages using the build hooks, as this can lead to unexpected compatibility issues.

Example build script

A full worked example of using the build hooks follows.

  • Create a before-rhino-install build hook script with the contents

#!/bin/bash

pwd
cat hello.txt

and a file called hello.txt with the contents Hello, world!. Ensure the before-rhino-install script has the user-executable permission bit set, for example, by using chmod +x before-rhino-install.

  • Compress these two files into an archive named custom-build.zip using the command zip custom-build.zip before-rhino-install hello.txt.

  • Include this zip file in the same directory as the Rhino license when running the VMBC.

  • During the build process, the before-rhino-install script will be executed prior to the installation of Rhino.

  • When the VM boots, you will be able to find this script in the /home/<username>/install/build-hooks/scripts directory.

  • There will also be a /home/<username>/install/build-hooks/output directory containing one file, before-rhino-install.out, whose contents will be:

/home/<username>/install/build-hooks/workspace
Hello, world!

  • You can also find the above before-rhino-install.out file in the target directory on the machine running VMBC.

Previous page Next page