HorizonScript Keys
Introduction
A HorizonScript file is, at its core, a collection of values that determine the actions and configuration values used to transform a computer from an indeterminate state to a well-known state running Adélie Linux. These values are categorised into keys, which is a logical unit of a value.
This chapter defines and specifies for every valid key for a HorizonScript file: its name, its purpose, its format, and one or more example values with explanations.
Required Keys
Each key specified in this section is required to be present in a HorizonScript. If any key from this section is missing, the HorizonScript will be considered invalid and Horizon Runner will not execute it.
network
Name
network
Purpose
The network key determines if the target computer will support networking or not. If the value is true, the computer will support networking, and at least one netaddress key will then be required.
Format
The network key is a Boolean value — valid values are true and false. network must appear exactly once in a HorizonScript.
Example
The network Key
network true
This enables networking for the target computer.
hostname
Name
hostname
Purpose
The hostname key determines the hostname of the target computer. This key is always required, even when the target computer will not participate in a network. The computer's hostname is used on shell prompts, most window manager launchers, and in log files.
Format
The hostname key is a string value that must contain only alphanumeric characters and optionally one or more '.' characters. If hostname contains one or more '.' characters, all content before the first '.' is considered the hostname, and all content after the first '.' is considered the domain name. hostname must appear exactly once in a HorizonScript.
Examples
The hostname Key — Setting a Host Name
hostname gwyn
This sets the hostname of the target computer to gwyn.
The hostname Key — Setting a Host Name and Domain Name
hostname gwyn.foxkit.internal
This sets the hostname of the target computer to gwyn.foxkit.internal.
pkginstall
Name
pkginstall
Purpose
The pkginstall key lists the packages that will be installed on the target computer.
Format
The pkginstall is a space-separated list of APK packages. They must be available in the repositories used during the installation process. pkginstall must appear at least once in a HorizonScript. There is no limit to the number of times pkginstall may be specified; each one will append to the list of packages to install.
Examples
The pkginstall Key — Simple Usage
pkginstall adelie-base-posix kde x11
This installs the adelie-base-posix, kde, and x11 packages on the target computer.
The pkginstall Key — Multiple Invocations
pkginstall adelie-base-posix
pkginstall x11 i3wm
pkginstall claws-mail
This installs the adelie-base-posix, x11, i3wm, and claws-mail packages on the target computer. This advanced usage may be useful if you use a templating engine to generate HorizonScript files.
Optional Keys
Each key specified in this section may be present in a HorizonScript. This section additionally defines the default value or action taken if the specified key is not present.
language
Name
language
Purpose
The language key determines the default natural language for the target computer. The value of this key will be used to configure the LANG and LC_ALL environment variables, in addition to installing language packs for certain software.
Format
The language key is a string value that specifies a valid locale code. A locale code must match one of the following formats: xx, or xx_YY, or xx_YY.UTF-8, where xx is a valid ISO 639-1 language code, and YY is a valid ISO 3166-1 country code. language may appear at most once in a HorizonScript.
Default
If the language key is not present, no setting will be defined for the LANG or LC_ALL environment variables. Most software treats this as either "C.UTF-8" or "en_US.UTF-8". No language packs will be installed for software that supports multiple language; due to English being the de facto language of software engineering, this implies all software will run in English.
Examples
The language Key — Simple Language
language cy
This sets the language of the target computer to Welsh.
The language Key — Language with Country Localisation
language fr_CA
This sets the language of the target computer to Canadian French.
keymap
Name
keymap
Purpose
The keymap key determines the keyboard layout used for input on the target computer.
Format
The keymap key is a string value that specifies the name of a keyboard layout. Valid keyboard layouts are listed in /etc/console-setup/ckb/rules/xorg.lst under the ! layout heading. keymap may appear at most once in a HorizonScript.
Default
If the keymap key is not present, the target computer will use the default keyboard settings from Linux. These settings are architecture-dependent, but almost universally use a US QWERTY-style layout.
Example
The keymap Key
keymap fr
This sets the keyboard layout of the target computer to French AZERTY.
firmware
Name
firmware
Purpose
The firmware key determines if the target computer will load potentially insecure, proprietary firmware.
Format
The firmware key is a Boolean value — valid values are true and false. firmware may appear at most once in a HorizonScript.
Default
If the firmware key is not present, the target computer will not load proprietary firmware. This is to ensure the integrity, security, and reliability of the target computer.
Example
The firmware Key
firmware false
This explicitly disables loading of firmware on the target computer.
netaddress
Name
netaddress
Purpose
The netaddress key determines the network configuration used on the target computer.
Format
The netaddress key is a space-separated list of network configuration information:
The kernel interface name. If the interface specified does not exist, the system will issue a soft error (logging the failure but attempting to continue with installation).
The addressing type. Valid values are dhcp for DHCP v4 and v6, slaac for IPv6 Stateless Automatic Address Configuration, and static for Administrator-specified addressing. The list must end here unless the address type specified is static. Any additional items constitute a configuration error and an invalid HorizonScript.
The IP address. The value specified must be a valid IPv4 or IPv6 address.
The prefix or network mask. The value must be either:
A whole number in the range of 1-32 for IPv4 addresses, or 1-64 for IPv6 addresses.
An IPv4 network mask, in the format octet.octet.octet.octet.
Optionally, the default gateway. The value specified must be a valid IP address of the same family as the IP address specified in item 3.
netaddress must not appear unless network is true. If network is true, then netaddress must appear at least once, and may appear up to 255 times per interface.
Default
There is no default for this key. It is invalid to enable networking and not provide at least one netaddress key.
Example
The netaddress Key — Simple DHCP
netaddress eth0 dhcp
This configures the target computer to use DHCP on interface eth0.
The netaddress Key — Static Addressing
netaddress eth0 2001:db8::1337 64 2001:db8::1
netaddress eth0 198.51.100.37 24 198.51.100.1
This configures the target computer to use the addresses 2001:db::1337/64 and 198.51.100.37/24 on interface eth0. The default gateways are 2001:db::1 and 198.51.100.1.
nameserver
Name
nameserver
Purpose
The nameserver key determines the DNS server used for name queries on the target computer.
Format
The nameserver key takes either an IPv4 address or IPv6 address. Any other value is invalid. The nameserver may appear up to four times in a HorizonScript, or be omitted. It is valid to specify nameserver even if network is false, but name queries will not function properly without a network configuration.
Default
If the nameserver key is not specified, name queries requiring the DNS will not succeed on the target computer.
Example
The nameserver Key
nameserver 2620:fe::fe
This configures the target computer to use Quad9's public resolver, 2620:fe::fe, for name queries.
netssid
Name
netssid
Purpose
The netssid key determines the wireless networking configuration on the target computer.
Format
The netssid is a space-separated list of wireless networking configuration information:
The kernel interface name. If the interface specified does not exist, the system will issue a soft error (logging the failure but attempting to continue with installation).
The SSID name to connect to. This must be a string value enclosed by ASCII double-quotes ("). System behaviour is undefined if the SSID name contains an ASCII double-quote.
The security type of the SSID. Valid values are none for an open access point, wep for a WEP passphrase, and wpa for a WPA pre-shared key (PSK).
If the security type is not none, the passphrase or pre-shared key. WPA PSKs may be specified in hexadecimal or as a raw string. The remainder of the line will be used verbatim.
Default
If the netssid key is not specified, no wireless network configuration will be present on the target computer.
Examples
The netssid Key — Open Network
netssid wlan0 "h" none
This configures the target computer to connect to the access point with name h, with no security.
The netssid Key — WEP Network
netssid wlan0 "Hophop" wep omgitsarabbit
This configures the target computer to connect to the access point with name Hophop, with the WEP passphrase omgitsarabbit.
The netssid Key — WPA2 Network
netssid wlan0 "The New Fox 5G" wpa shh sekrit
This configures the target computer to connect to the access point with name The New Fox 5G, with the WPA PSK shh sekrit.
timezone
Name
timezone
Purpose
The timezone key determines the local time zone on the target computer.
Format
The timezone key is a string value that must correspond with a valid zoneinfo time zone name. A list of valid time zone names may be found using the following command on any Adélie Linux computer: find /usr/share/zoneinfo. timezone may appear at most once in a HorizonScript.
Default
If the timezone key is not specified, the target computer will use UTC (Universal Coordinated Time) as its time zone.
Example
The timezone Key
timezone Africa/Nairobi
This configures the target computer to use East Africa Time, as observed in Nairobi, Kenya, for the local time zone.
repository
Name
repository
Purpose
The repository key specifies the location of an APK package repository to use on the target computer. This repository will be used for initial installation, and added to the /etc/apk/repository file on the target computer.
Format
The repository key is a string value which must describe either an absolute local path or a HTTP or HTTPS location on the network. repository may appear up to ten times in a HorizonScript, or be omitted.
Default
If the repository key is not specified, the default repositories for Adélie Linux will be used:
https://distfiles.adelielinux.org/adelie/$VERSION/system
https://distfiles.adelielinux.org/adelie/$VERSION/user
where $VERSION is the version of Adélie Linux being installed. Additionally, if the firmware key is specified and set to true, the https://distfiles.apkfission.net/adelie-$VERSION/nonfree repository will be added. If repository is specified, none of these repositories will be used unless manually specified.
Example
The repository Key
repository https://mirrors.servercentral.com/adelie/1.0/system
repository https://mirrors.servercentral.com/adelie/1.0/user
This configures the target computer to use the Server Central mirrors.
signingkey
Name
signingkey
Purpose
The signingkey key specifies a key to trust for APK package repositories.
Format
The signingkey key is a string value which must describe either an absolute local path or an HTTPS location on the network. It is not valid to use an HTTP connection for signingkey. signingkey may appear up to ten times in a HorizonScript, or be omitted.
Default
If the signingkey key is not specified, the Adélie Linux repository signing key will be used. Additionally, if the firmware key is specified and set to true, the APK Fission signing key will be used. If signingkey is specified, none of these signing keys will be trusted unless manually specified.
Example
The signingkey Key
signingkey /etc/apk/keys/packages@adelielinux.org.pub
signingkey https://packages/builder@ourcompany.net.pub
This configures the target computer to use the default Adélie Linux repository signing key, and also a repository signing key that is available for download from the URL https://packages/builder@ourcompany.net.pub.
Disk Partitioning Keys
This section describes the keys used for partitioning one or more hard disk drives using HorizonScript. Of these, only the mount key is required to be present in a valid HorizonScript.
Sizing
Purpose
All disk partitioning keys that take a size argument shall follow the format described in this section. There are three forms of valid size that may be specified.
Format #1: Block Size
Block sizing format is: number{K|M|G|T}. K, M, G, and T represent IEC binary prefixes; for example, "150G" would specify 150 GiB.
Format #2: Percentage
Percentage format is: number%, where number is a number from 1 to 100 inclusive. It is invalid to specify multiple partitions that would use more than 100% of a containing block device.
Format #3: Fill
The literal string fill specifies that the partition shall fill the remaining space of the containing block device. No partitions may come after one that specifies fill on the same containing block device.