Chapter 9. Creating Images

Table of Contents

Using the Image Creation System
Backend-Specific Options
Archive Backend (tar, tgz, tbz, txz)
ISO Backend (iso)
Writing a Custom Backend
Registering Your Custom Backend

You can use the Image Creation system to create various types of images, including bootable CD/USB images and root filesystem tarballs you can deploy later.

Using the Image Creation System

The Image Creation system takes a HorizonScript as input, and uses it to generate an image of the desired type. The primary command for interacting with the Image Creation system is hscript-image.

You can view a list of available image types by running hscript-image -t list. The hscript-image command will print a list of available image types. The first column contains the type code which you pass to the -t paramater, and the second column provides you a short explanation of what type of image will be created with the specified type code.

The output file name can be controlled by the -o parameter. For example, hscript-image -t iso -o mydisc.iso will write the image to mydisc.iso.

Backend-specific options can be specified using the -b parameter. You may specify the -b parameter multiple times, to provide multiple options to the specified backend. Backend-specific options are discussed later in the per-backend sections.

Temporary files, including the entire image root directory, are written to a directory called the intermediate directory, or IR directory. The default path for this is /tmp/horizon-image; you may specify the -i parameter to change it. For example, hscript-image -i /opt/horizon/imagedir will write the temporary files to /opt/horizon/imagedir. The temporary files are not removed after running the hscript-image command, whether or not the run was successful. This allows you to inspect the contents of the image without extracting them. You may remove the directory at any time after the hscript-image process ends.

Specify the installfile at the end of the command line. For example, hscript-image -t iso -o mydisc.iso $HOME/mydisc.installfile will use the script located at $HOME/mydisc.installfile. If you do not specify an installfile, the one at /etc/horizon/installfile will be used. You may also specify - to use stdin.

Backend-Specific Options

Each backend in the Image Creation system has its own set of defaults and available options. The backends provided with the Horizon system are documented in this section.

Archive Backend (tar, tgz, tbz, txz)

No backend-specific options are available for the libarchive backend.

ISO Backend (iso)

Available options for the ISO backend


Preserve the IR directory between runs. This can save significant time downloading packages if you are using a slow connection, but does not support HorizonScripts that contain user accounts other than root.


Specifies the location of the file that will be used as /etc/issue for the CD's operating environment. /path/to/issue should be a plain text file that exists on the current system.


Specifies the location of the file that will be used as .VolumeIcon.icns for the CD. /path/to/icns should be a ICNS file that exists on the current system.


Specifies the location of the file that will be executed just before creating the actual ISO file. /path/to/ should be an executable file that exists on the current system. A default script is provided for all Tier 1 architectures that correctly configures boot parameters. You should only override this script if you know exactly what you are doing.

iso-params="parameter1 parameter2=value ..."

Specifies additional parameters to pass to xorriso.

Writing a Custom Backend

The Image Creation system is easily extensible. You can check out the Horizon source code and add a new backend with minimal effort. The image/backends includes a README that describes the basic design of backend modules. The libarchive backend is also a good example to use; the entire module is only 188 lines of C++.

Registering Your Custom Backend

Your backend module needs to have a constructor function (unrelated to C++ class constructors) that registers the backend with the Image Creation system. You must call Horizon::Image::BackendManager::register_backend from your constructor function to register your backend. The following is a short example based on the libarchive backend.

Example 9.1. Registering a custom backend in a constructor function

#include <image/backends/basic.hh>
#include "xyzzy.hh"

void register_xyzzy_backend() {
    {"xyzzy", "Create an XYZZY image (.xyzzy)",
        [](const std::string &ir_dir, const std::string &out_path,
           const std::map<std::string, std::string> &opts) {
            return new XyzzyBackend(ir_dir, out_path, opts);