Chapter 7. Authoring and Maintaining HorizonScripts

Table of Contents

Introduction to HorizonScript
Authoring HorizonScripts
Using System Installation
Using a text editor
Using JSON
Advanced Usage of HorizonScripts
Validating HorizonScripts
Simulating Execution of a HorizonScript

A HorizonScript defines the configuration of a computer. The Horizon Executor takes a HorizonScript as input, and configures a computer using the information provided.

This chapter will introduce you to concepts and best practices related to authoring and maintaining HorizonScript files.

A HorizonScript is a plain-text file. Each line of text has a key, which specifies what the line is configuring, and one or more values, which is the configuration data.

The Horizon Executor configures the target computer, or target. The target computer is the computer on which you are configuring the environment.

All HorizonScript files are required to specify at least four keys: network, which determines whether networking will be enabled on the target; hostname, which determines the host name of the target; pkginstall, which determines what packages will be installed on the target; and rootpw, which determines the encrypted root password for the target.

For a detailed list of all valid keys, consult the HorizonScript Reference at https://horizon.adelielinux.org/script/.

You may author a HorizonScript in one of three ways:

  • Using System Installation: You can run the System Installation wizard in Runtime Environment mode. When you finish with the wizard, instead of installing to your computer, it will save a HorizonScript to a location you specify.

  • Using a text editor: You can write HorizonScripts using a text editor. Ensure that the text editor you use does not use formatting; HorizonScript files are plain text only.

  • Using JSON: The Horizon system defines a JSON schema for representing HorizonScript files. If you have a tool capable of writing a properly-formatted JSON file, you may use the hscript-fromjson utility to generate a HorizonScript.

Each of these methods should be evaluated based on your desired use case. Note, however, that using a text editor may allow you to configure some advanced settings that the other methods do not support.

Install the horizon-wizard package on your workstation. If you are not using an APK-based Linux distribution, you may download releases from https://horizon.adelielinux.org/.

Run System Installation. Refer to the section called “Navigating System Installation” and Chapter 4, Selecting System Options for more information on how to use System Installation.

At the end of System Installation, you will be prompted for a location to write the HorizonScript. System Installation will write the HorizonScript and then close. You may then review or edit it using a text editor.

You can write HorizonScript files in a text editor. Typically, HorizonScript files are named "installfile" or "name.installfile". You can also add comments on their own line by prefixing the comment with a "#" character.

A simple HorizonScript that configures a computer called "test-web" to serve a Ruby Web site might look like:

Example 7.1. A simple HorizonScript

network true
netaddress eth0 static 10.1.9.8 255.255.0.0 10.1.0.1
nameserver 9.9.9.9
rootpw ...
hostname test-web
pkginstall adelie-base-posix dash-binsh easy-kernel easy-kernel-modules lighttpd openrc ruby-full uwsgi-rack
# Enable lighttpd on startup:
svcenable lighttpd
                

If you have a properly-formatted JSON file, for example from a vendor-provided tool, you can use it to generate a HorizonScript file.

Example 7.2. A simple JSON file

{
 "hostname": "horizon-json-testmachine.adelielinux.org",
 "packages": ["adelie-base-posix", "easy-kernel", "easy-kernel-modules", "netifrc", "openrc", "s6-linux-init"],
 "rootpw": "...",
 "root": "/dev/sda1",
 "netaddresses": [{"id":"eth0", "interface":"eth0", "addr-type":"dhcp"}],
 "nameservers": ["9.9.9.9"]
}
                

Procedure 7.1. Generating a HorizonScript from a JSON file

  1. Locate the JSON file on your computer.

  2. Open a Terminal window.

  3. Run hscript-fromjson output.installfile /path/to/file.json, where output.installfile is the desired location for the HorizonScript, and /path/to/file.json is the path to the JSON file.

The HorizonScript format allows for many different ways to author and extend configurations.

One of the ways to extend configurations is via the inherit system. Using this system, you write a base HorizonScript containing common options that apply to a group of computers, and then write per-computer configurations that inherit from the base HorizonScript.

A HorizonScript can only inherit from a single HorizonScript. However, you can use nesting and have the base HorizonScript inherit from another base.

The following is an example of a typical multi-level nested HorizonScript:

Example 7.3. Nesting HorizonScripts

# base.installfile
network true
netaddress eth0 dhcp
nameserver 9.9.9.9
# Install KDE and X11 on all workstations.
pkginstall adelie-base-posix dash-binsh easy-kernel easy-kernel-modules kde openrc x11
svcenable udev boot
svcenable elogind
svcenable sddm
            
# cad.installfile
pkginstall blender freecad libreoffice
inherit base.installfile
            
# taylors-workstation.installfile
hostname taylor-workstation
rootpw ...
username taylor
useralias taylor Taylor
usergroup taylor wheel,users,audio,video,usb,lp
userpw taylor ...
inherit cad.installfile
            

Another way to generate HorizonScripts is by using a templating engine. Choosing and using a templating engine is beyond the scope of this document, but a few options may include Template::Toolkit for Perl, Jinja for Python, and ERB for Ruby. Any templating engine capable of producing plain text files may be used to generate HorizonScript files.

Once you have authored your HorizonScript, you may run the HorizonScript Validation Utility to ensure that the HorizonScript is syntatically valid. The HorizonScript Validation Utility uses the same parsing engine that the Horizon Executor uses, so you can be assured that if the Validation Utility finds no issues, your script will have no parsing issues during execution.

[Note] Note

Passing validation does not mean that a script will execute successfully, only that it will be parsed successfully. For example, the Validation Utility cannot ensure that the disk structure you have specified will fit on the target computer's disk drive.

Procedure 7.2. Validating a script using the HorizonScript Validation Utility

  1. Locate the HorizonScript on your computer.

  2. Open a Terminal window.

  3. Run hscript-validate /path/to/installfile, where /path/to/installfile is the path to your HorizonScript.

The HorizonScript Validation Utility outputs log messages in the same format as the Horizon Executor. For more information on interpreting log messages from the HorizonScript Validation Utility, refer to the section called “Reviewing the Executor log file”.

If you believe your HorizonScript may have multiple errors, you can use the -k flag (which stands for "Keep going") to have the Validation Utility run through the entire script instead of stopping at the first error.

One way to ensure your HorizonScript will execute in the way you expect is to use the HorizonScript Simulation Utility. The Simulation Utility will log every action that the Executor will take, and will also output equivalent shell commands to what the Executor will run.

Procedure 7.3. Simulating a script using the HorizonScript Simulation Utility

  1. Locate the HorizonScript on your computer.

  2. Open a Terminal window.

  3. Run hscript-simulate /path/to/installfile, where /path/to/installfile is the path to your HorizonScript.

The HorizonScript Simulation Utility outputs log messages in the same format as the Horizon Executor. For more information on interpreting log messages from the HorizonScript Simulation Utility, refer to the section called “Reviewing the Executor log file”.

The HorizonScript Simulation Utility writes log messages to stderr, and the equivalent shell commands to stdout. If you want to read the log messages and discard the shell commands, you may run the hscript-simulate command with stdout redirected to /dev/null, as in hscript-simulate /path/to/installfile >/dev/null. Similarly, if you want to save the shell commands to a file, you may redirect stdout to a file, as in hscript-simulate /path/to/installfile >myscript.sh.