The Horizon Runner is the component of Project Horizon that configures a computer to match an input HorizonScript.

The system needs to load the HorizonScript into memory. If the HorizonScript is a local file, the system needs to ensure it is present and readable. If the HorizonScript is remote, the system needs to proceed to Network Configuration before continuing.

The system shall determine if the HorizonScript is stored locally or remotely using the following algorithm: If the path to the HorizonScript is not provided, assume the HorizonScript is remote and end the calculation. Priority: Low. If the path to the HorizonScript begins with a single "/" followed by an alphanumeric character, the HorizonScript is local. If the path to the HorizonScript begins with a recognised valid protocol for downloading a HorizonScript followed by the characters "://", the HorizonScript is remote. If the path to the HorizonScript begins with an alphanumeric character, the HorizonScript is local and relative to the path /etc/horizon. If the path to the HorizonScript does not match any of the rules specified before this line, the path provided is invalid and the system shall return an error describing the specified path and the fact it is invalid. If the HorizonScript is local, the system shall ensure the HorizonScript specified exists at the specified path, is readable by the system, and is the correct format. If the HorizonScript fails the tests in Runner.Locate.Local, the system shall return an error describing the reason the HorizonScript could not be used. If the HorizonScript is remote, the system shall configure the network and then ensure the HorizonScript specified is accessible, as described in the following requirements sections. The system shall use the network settings configured by the Administrator on the command line, if they have been provided. If no network configuration was provided on the command line, the system shall initiate a DHCP request on each available network interface, waiting for a 15 second time out period before continuing to the next network interface. An "available network interface" is defined as a non-loopback network interface that currently has a carrier signal. If no network configuration can be found using DHCP, the system shall return an error describing the inability to configure a network connection. If no HorizonScript path was provided, the system shall download the HorizonScript from a TFTP server using the filename MACADDRESS.installfile where MACADDRESS is the MAC address of the active network adaptor with colons (:) replaced by dashes (-). The system shall use the following algorithm to determine the TFTP server, using the first match. The TFTP server specified on the command line, if one was provided. The TFTP server specified in the DHCP options, if DHCP was used to configure the network and the DHCP response provided one. The DHCP server, if DHCP was used to configure the network. The default gateway IP. The system shall ensure that the server where the HorizonScript is kept is reachable over the protocol specified and that the HorizonScript exists. The system shall download the HorizonScript from the remote server to /etc/horizon/.

The system needs to validate the supplied HorizonScript before executing it.

If the HorizonScript fails any validation step performed by the system, the system shall report the error. If the system is running in an installation environment, the system shall report validation step failure to the listening agent. The system shall support a mode where the system will continue validation after encountering a validation failure, to display all validation failures for a given HorizonScript. The system shall ignore any lines that are entirely blank, or start with the ASCII octothorpe (#) character. The system shall verify the presence of each required keyword in the HorizonScript: mount, network, hostname, pkginstall, and rootpw. The system shall verify that a single network entry is present in the HorizonScript, and that the value is either true or false. If the value in the HorizonScript for the network key is true, the system shall verify that at least one netaddress key is present. The system shall verify that each netaddress key has a valid form of at least two values in a space-separated tuple. The system shall verify that the second value in each netaddress tuple is either dhcp, slaac, or static. The system shall verify that each netaddress key is a two value tuple if the second value is dhcp. The system shall verify that each netaddress key is either a four value tuple or a five value tuple if the second value is static. If the system is running in an installation environment, the system shall ensure that the interface specified as the first value in each netaddress tuple is present on the system. Failure of this requirement is a "soft" error. If the second value of the netaddress key is static, the system shall ensure that the third value in the tuple is a valid IPv4 or IPv6 address. If the second value of the netaddress key is static, the system shall ensure that the fourth value in the tuple is a valid prefix length, in the form of a whole number between 0 and 32 inclusive if the third value is an IPv4 address, a whole number between 0 and 128 inclusive if the third value is an IPv6 address, or a network mask in the form of four octets separated by the period (.) symbol if the third value is an IPv4 address. If the second value of the netaddress key is static, and the tuple contains a fifth value, the system shall ensure that the fifth value is a valid IP address of the same type as the third value in the tuple. The system shall verify that netaddress is not specified more than 255 times per interface. The system shall verify the validity of any present netssid key. The system shall verify that each netssid key has a valid form of either three values or four values in a space-separated tuple. If the system is running in an installation environment, the system shall ensure that the interface specified as the first value in each netssid tuple is present on the system and supports wireless extensions. The system shall verify that the second value of each netssid tuple is a valid SSID enclosed in ASCII double-quotes ("). The system shall verify that the third value of each netssid tuple is a valid security type: either none, wep, or wpa. If the third value of a netssid tuple is a valid security type and not none, the system shall ensure that the netssid tuple has a fourth value that specifies the security key. The system shall verify that the HorizonScript contains zero or one netconfigtype key. If the HorizonScript contains a netconfigtype key, the system shall ensure that the netconfigtype key has a valid form of a single string containing a recognised network configuration type. If the value of the netconfigtype key is netifrc, the system shall write any network configuration in a manner that can be used by the netifrc package. If the value of the netconfigtype key is eni, the system shall write any network configuration to a /etc/network/interfaces file that conforms to the standard provided. The system shall verify any nameserver keys contained in the HorizonScript. The system shall verify that the value of each nameserver key is an IPv4 or IPv6 address. The system shall verify that the HorizonScript contains exactly one hostname key. The system shall verify that the value for the hostname key contains only alphanumeric and optionally one or more period (.) characters. The system shall verify that the value for the hostname key begins with an alphanumeric character. The system shall verify that the value for the hostname key does not exceed 320 characters in length. The system shall verify that the value for each part of the value of the hostname key, separated by an ASCII period (.), does not exceed 64 characters in length. The system shall verify that the HorizonScript contains at least one pkginstall key. The system shall verify that the HorizonScript contains exactly one rootpw key. The system shall verify that the value for the rootpw key is in the format: $, either 2 for Blowfish or 6 for SHA-512, $, and then variant data. The system shall verify that the HorizonScript contains zero or one arch key. The system shall warn if the value specified in arch is not recognised as a valid APK-supported CPU architecture. This shall not be a fatal error, because not all Tier 3 systems may be recognised. The system shall verify that the HorizonScript contains zero or one language key. The system shall verify that the value of the language key, if present, is a valid ISO 639-1 language code, optionally followed by an ASCII underscore (_) and ISO 3166-1 country code, optionally followed by the string literal .UTF-8. The system shall verify that the HorizonScript contains zero or one keymap key. The system shall verify that the value of the keymap key, if present, is a valid keyboard layout available for use in an Adélie Linux system. The system shall verify that the HorizonScript contains zero or one firmware key. The system shall verify that the value of the firmware key, if present, is either true or false. If the system has firmware support compiled out, the system shall verify that the value of the firmware key, if present, is false. The system shall verify that the HorizonScript contains zero or one timezone key. The system shall verify that the value of the timezone key, if present, represents a valid zoneinfo time zone name. The system shall verify that the HorizonScript contains zero to ten repository keys. The system shall verify that the value of each repository key is either an absolute local path beginning with an ASCII oblique (/), or a valid URL utilising the HTTP or HTTPS protocols. The system shall verify that the HorizonScript contains zero to ten signingkey keys. The system shall verify that the value of each signingkey key is either an absolute local path beginning with an ASCII oblique (/), or a valid URL utilising the HTTPS protocol. The system shall verify that the HorizonScript contains zero to 255 username keys. The system shall verify that the value of each username key is unique. The system shall verify that the value of each username key does not match a system-defined account. The system shall verify that the value of each username key is a valid Linux user account name. The system shall verify that the HorizonScript contains a number of useralias keys equal or less than the number of username keys. The system shall verify that each useralias key has a valid form of two values in a space-separated tuple, with the second value reading to the end of the line (optionally containing spaces). The system shall verify that the first value in each useralias key tuple is an account name specified in a username key. The system shall verify that only one useralias key is specified per account name. The system shall verify that the HorizonScript contains a number of userpw keys equal or less than the number of username keys. The system shall verify that each userpw key has a valid form of two values in a space-separated tuple. The system shall verify that the first value in each userpw key tuple is an account name specified in a username key. The system shall verify that only one userpw key is specified per account name. The system shall verify that the second value for each userpw key tuple is in the format: $, either 2 for Blowfish or 6 for SHA-512, $, and then variant data. If a username key exists with no matching userpw key tuple, the system shall display a warning message that the user account will have no passphrase set. The system shall verify that the HorizonScript contains a number of usericon keys equal or less than the number of username keys. The system shall verify that each usericon key has a valid form of two values in a space-separated tuple. The system shall verify that the first value in each usericon key tuple is an account name specified in a username key. The system shall verify that only one usericon key is specified per account name. The system shall verify that the second value of each usericon key tuple is either an absolute local path beginning with an ASCII backslash (/), or a valid URL utilising the HTTP or HTTPS protocols. The system shall verify any usergroups keys contained in the HorizonScript. The system shall verify that each usergroups key has a valid form of two values in a space-separated tuple. The system shall verify that the first value in each usergroups key tuple is an account name specified in a username key. The system shall verify that all usergroups key tuples for a specified account name specify a combined total of sixteen or fewer groups. The system shall verify that a group is specified only once for each account name. The system shall verify that each group specified is a valid system-defined group name that is present in the base system image /etc/group file. The system shall verify any diskid keys contained in the HorizonScript. The system shall verify that each diskid key has a valid form of two values in a space-separated tuple, with the second value reading to the end of the line (optionally containing spaces). The system shall verify that the first value of each diskid key tuple is unique in the HorizonScript. If the system is running in an installation environment, the system shall ensure that the first value of each diskid key tuple specifies a valid block device. The system shall verify any disklabel keys contained in the HorizonScript. The system shall verify that each disklabel key has a valid form of two values in a space-separated tuple. The system shall verify that the first value of each disklabel key tuple is unique in the HorizonScript. If the system is running in an installation environment, the system shall ensure that the first value of each disklabel key tuple specifies a valid block device. The system shall verify that the second value of each disklabel key tuple is one of the following three values: apm, mbr, or gpt. The system shall verify any partition keys contained in the HorizonScript. The system shall verify that each partition key has a valid form of three or four values in a space-separated tuple. The system shall verify that the second value of each partition key tuple is a valid positive whole integer. The system shall verify that the union of the first and second values in each partition key tuple are unique. If the system is running in an installation environment, the system shall ensure that the first value of each partition key tuple specifies a valid block device. The system shall verify that the third value in each partition key tuple specifies a valid size as described in . If a partition key tuple contains a fourth value, the system shall verify that the fourth value of the partition key tuple is a valid type code, which is one of the following two values: boot, or esp. The system shall verify any lvm_pv keys contained in the HorizonScript. The system shall verify that the value of each lvm_pv is an absolute path to a device node. If the system is running in an installation environment, the system shall verify that the value of each lvm_pv key specifies a valid block device or a block device that will be created. The system shall verify any lvm_vg keys contained in the HorizonScript. The system shall verify that each lvm_vg key has a valid form of two values in a space-separated tuple. If the system is running in an installation environment, the system shall verify that the first value of each lvm_vg key tuple specifies a valid block device or a block device that will be created. If the system is running in an installation environment, the system shall verify that the first value of each lvm_vg key tuple specifies a valid physical volume or a physical volume that will be created. The system shall verify that the second value of each lvm_vg key specifies a string that would be valid as an LVM volume group name. The system shall verify any lvm_lv keys contained in the HorizonScript. The system shall verify that each lvm_lv key has a valid form of three values in a space-separated tuple. If the system is running in an installation environment, the system shall verify that the first value of each lvm_lv key specifies a valid LVM volume group, or one specified in an lvm_vg key. The system shall verify that the second value of each lvm_lv key specifies a string that would be valid as an LVM logical volume name. The system shall verify that the third value in each lvm_lv key tuple specifies a valid size as described in . The system shall verify any encrypt keys contained in the HorizonScript. The system shall verify that the value of each encrypt key is a string value that is an absolute path to a device node, with an optional second value as a space-separated tuple. If the system is running in an installation environment, the system shall verify that the value of each encrypt key, and the first value of each encrypt key tuple, specifies a valid block device or a block device that will be created. The system shall verify that the value of each encrypt key, and the first value of each encrypt key tuple, is unique to all encrypt keys and encrypt key tuples in the HorizonScript. The systemm shall verify any fs keys contained in the HorizonScript. The system shall verify that each fs key has a valid form of two values in a space-separated tuple. If the system is running in an installation environment, the system shall verify that the first value of each fs key tuple specifies a valid block device or a block device that will be created. The system shall verify that the second value of each fs key tuple specifies a valid file system supported by Horizon, using lower case characters. The system shall verify that the first value of each fs key is unique in the HorizonScript. The system shall verify that the HorizonScript contains at least one valid mount key. The system shall verify that each mount key has a valid form of two or three values in a space-separated tuple. If the system is running in an installation environment, the system shall verify that the first value of each mount key tuple specifies a valid block device or a block device that will be created. The system shall verify that the second value of each mount key tuple specifies a valid mount point beginning with a /. The system shall verify that the second value of each mount key is unique. The system shall verify that one mount key tuple specifies the root (/) mount. If the system is running in a runtime environment, the system shall verify that all of the packages specified in pkginstall keys are available in the specified repositories; either the repositories specified in repository keys, or the system-default repositories if no repository keys have been specified.

The system executes the instructions provided in the HorizonScript, in the specified order. The system reports progress, and all warnings and errors, to the listening agent. Once the system has finished, it reports the completion status to the listening agent.

The system shall execute the instructions provided in the HorizonScript in the order described. The system shall report any exception encountered during execution to the listening agent, following the specification in . If an operation has taken more than 10 seconds, the system shall report the status of the operation to the listening agent, following the specification in . When the system begins a step, the system shall report the step as beginning to the listening agent, following the specification in . When the system completes a step, the system shall report the step as completed to the listening agent, following the specification in . The system shall validate the HorizonScript, using the process specified in the section , before execution. If the HorizonScript fails validation, the system shall report a fatal exception () and stop execution. The system shall verify that each block device specified in a diskid key tuple matches the identification string provided. If any block device fails the diskid identification string check, the system shall consider this a fatal error and stop execution of the HorizonScript. The system shall create any disklabels specified in disklabel key tuples. If a disklabel already exists on the block device where a new disklabel will be written, the system shall erase the existing disklabel before creating the new disklabel. If a disklabel cannot be created due to an I/O error, or due to a non-existent block device, the system shall consider this a fatal error and stop execution of the HorizonScript. The system shall create any partitions specified in partition key tuples. The system shall consider any failure to create a partition as a fatal error and stop execution of the HorizonScript, unless otherwise specified by a requirement in this tree. If a partition cannot be created due to an I/O error, or due to a non-existent block device, the system shall consider this condition a fatal error and stop execution of the HorizonScript. The system shall consider a numbering error, defined as creating a partition with the same index as an existing partition or creating a partition with an invalid index for the block device's label, a fatal error and stop execution of the HorizonScript. If the partition cannot be created because it already exists, and all properties are identical (index, size, type codes), the system shall continue as if the partitioning succeeded. If any lvm_pv keys are specified, and any encrypt keys specify the block device where an LVM physical volume will be created, the system shall execute the encrypt keys that correlate with lvm_pv keys before executing the lvm_pv keys. The system shall create any LVM physical volumes specified in lvm_pv keys. If a LVM physical volume cannot be created due to an I/O error, or due to a non-existent block device, the system shall consider this condition a fatal error and stop execution of the HorizonScript. The system shall create any LVM volume groups specified in lvm_vg keys. If an LVM volume group with the specified name already exists on the computer, the system shall consider this condition a fatal error and stop execution of the HorizonScript unless the volume group is using the same physical volume as specified, in which case the system shall continue as if creation of the LVM volume group succeeded. If an LVM volume group cannot be created due to an I/O error, or due to a non-existent physical volume, the system shall consider this condition a fatal error and stop execution of the HorizonScript. The system shall create any LVM logical volumes specified in lvm_lv keys. If an LVM logical volume cannot be created due to an I/O error, or due to a non-existent volume group, the system shall consider this condition a fatal error and stop execution of the HorizonScript. The system shall create LUKS containers specified in encrypt keys. If an encrypt key does not specify a passphrase, the system shall prompt the User for a passphrase via the listening agent, following the specification in . The system shall create file systems specified in fs key tuples. If a file system is present on the block device where a new file system is to be created, the system shall overwrite the existing file system. If a file system cannot be created due to an I/O error, or due to a non-existent block device, the system shall consider this condition a fatal error and stop execution of the HorizonScript. The system shall mount the file systems specified in mount keys, under the /target namespace. If a block device specified in a mount key tuple has a file system that is unreadable by the computer, the system shall consider this condition a fatal error and stop execution of the HorizonScript. If a mount option specified in a mount key tuple is invalid, and the file system successfully mounts without that option set, the system shall log a warning to the listening agent and proceed with installation. If a file system cannot be mounted due to an I/O error, or due to a non-existent block device, the system shall consider this condition a fatal error and stop execution of the HorizonScript. The system shall set the hostname of the computer to the hostname specified in the hostname key. The system shall write the hostname of the computer to the /etc/hostname file in the target namespace. If one or more repository keys are specified in the HorizonScript, the system shall write the repository locations to the /etc/apk/repositories file in the target namespace; otherwise, the system shall write the default repository locations to the /etc/apk/repositories file in the target namespace. If a version key is specified in the HorizonScript, and no repository keys are specified in the HorizonScript, the system shall use the value of the version key as the version portion of the default repository location(s) written to the target namespace. If a firmware key is specified in the HorizonScript, and the system is compiled with firmware support enabled, and the value of the firmware key is true, the system shall add linux-firmware to the list of packages to install. If no repository keys are specified in the HorizonScript, the system shall append the repository https://distfiles.apkfission.net/adelie-$VERSION/nonfree to the /etc/apk/repositories file in the target namespace, where $VERSION is the version of Adélie Linux being installed. The system shall write the wireless networking configuration specified by any netssid keys to the /etc/wpa_supplicant/wpa_supplicant.conf file in the target namespace. The system shall write the networking configuration specified by any netaddress keys to the /etc/conf.d/net file in the target namespace. This requirement is under discussion. If one or more nameserver keys are specified in the HorizonScript, the system shall write the nameservers specified to the /etc/resolv.conf file in the target namespace. If the hostname key contains a domain name part (at least one ASCII period . followed by at least one alphanumeric character), the system shall write the domain name to the /etc/resolv.conf file in the target namespace. If the value of the network key is true, the system shall execute the netssid, netaddress, and nameserver keys in the installation environment. If the value of the network key is true, the system shall use the networking configuration specified in any netaddress keys in the installation environment. If the value of the network key is true, the system shall use the wireless networking configuration specified in any netssid keys in the installation environment. If the value of the network key is true, the system shall use the nameservers specified in any nameserver keys in the installation environment. The system shall use the icons specified in any usericon key tuples for identification of users in user interface elements in the target namespace. If any usericon location is remote, the system shall download the contents of the remote file to the /usr/share/user-manager/avatars/remote/ directory in the target namespace. If any signingkey key is specified in the HorizonScript, the system shall copy all specified files to the /etc/apk/keys/ directory in the target namespace; otherwise, the system shall copy the default Adélie Linux signing keys to the /etc/apk/keys/ directory in the target namespace. If the firmware key is specified in the HorizonScript, and the system is compiled with firmware support enabled, and the value of the firmware key is true, then the system shall copy the APK Fission signing key(s) to the /etc/apk/keys/ directory in the target namespace. The system shall install all packages requested via the pkginstall key to the target namespace utilising the repositories configured in the target namespace. The system shall initialise the APK database in the target namespace before installing packages. If a arch key is specified in the HorizonScript, the system shall set the architecture of the target computer before installing packages and after initialising the APK database. The system shall use the signing keys as specified in any signingkey keys for ensuring package integrity during package installation. The system shall set the root password in the target namespace to the value specified in the rootpw key. If a language key is specified in the HorizonScript, the system shall add a script to /etc/profile.d setting the LANG environment variable to the value of the language key. If a keymap key is specified in the HorizonScript, the system shall set the XKBLAYOUT variable in the /etc/default/keyboard file in the target namespace to value of the keymap key. The system shall configure user accounts in the target namespace as specified in keys username, useralias, userpw, and usergroups. If a timezone key is specified in the HorizonScript, the system shall set the timezone in the target namespace to the specified timezone; otherwise, the system shall set the timezone in the target namespace to UTC. If the zoneinfo file for the specified timezone in the timezone key is missing in the target namespace, but present in the installation environment, the system shall copy the zoneinfo file from the installation environment to the /etc/localtime file in the target namespace. If a bootloader key is specified in the HorizonScript, the system shall perform the requested bootloader configuration. The system shall notify the listening agent that the HorizonScript has executed successfully and that the target is installed.