Chapter 2. HorizonScript Keys

Table of Contents

Introduction
Required Keys
network
hostname
pkginstall
rootpw
Optional Keys
arch
language
keymap
firmware
netconfigtype
netaddress
pppoe
nameserver
netssid
timezone
version
repository
svcenable
signingkey
bootloader
username
useralias
userpw
usericon
usergroups
Disk Partitioning Keys
Sizing
diskid
disklabel
partition
lvm_pv
lvm_vg
lvm_lv
encrypt
fs
mount

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.

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.

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. 

Example 2.1. The network Key

network true
                        

This enables networking for the target computer.


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. 

Example 2.2. The hostname Key — Setting a Host Name

hostname gwyn
                        

This sets the hostname of the target computer to gwyn.


Example 2.3. 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.


Name.  pkginstall

Purpose.  The pkginstall key lists the packages that will be installed on the target computer.

Format.  The pkginstall key 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.

Default.  If no anchor package (adelie-core, adelie-base, adelie-base-posix, adelie-base-lsb) is specified in any pkginstall key, adelie-core will be added automatically.

Examples. 

Example 2.4. 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.


Example 2.5. 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.


Name.  rootpw

Purpose.  The rootpw key provides the encrypted passphrase for the administrative root user on the machine.

Format.  The rootpw key is a string value containing a crypt(3) style, SHA-512 or Blowfish hashed passphrase. It is invalid to provide a plaintext passphrase.

Example. 

Example 2.6. The rootpw Key

rootpw $6$gumtLGmHwOVIRpQR$2M9PUO24hy5mofzWWf9a.YLbzOgOlUby1g0hDj.wG67E2wrrvys59fq02PPdxBdbgkLZFtjfEx6MHZwMBamwu/
                        

This sets the target computer's root passphrase to "Test Password". (Please do not use this passphrase.)


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.

Name.  arch

Purpose.  The arch key determines the CPU architecture of the target computer. The value of this key will be written to the /etc/apk/arch file in the target computer, which influences what packages are installed.

Format.  The arch key is a single string value that specifies a valid, APK-recognised CPU architecture. Currently recongised architectures for the Horizon 1.0 release include:

  • aarch64 (64-bit little-endian ARMv8)

  • aarch64_be (64-bit big-endian ARMv8)

  • alpha (64-bit DEC Alpha)

  • armel (32-bit ARMv5 or newer)

  • armhf (32-bit ARM with hardware VFP)

  • armv7 (32-bit ARMv7)

  • m68k (32-bit Motorola 68020 or newer)

  • mips (32-bit big-endian MIPS, MIPS III or newer)

  • mips64 (64-bit big-endian MIPS, MIPS III or newer)

  • mipsel (32-bit little-endian MIPS, MIPS III or newer)

  • mips64el (64-bit little-endian MIPS, MIPS III or newer)

  • pmmx (32-bit x86 with MMX extensions)

  • ppc (32-bit PowerPC)

  • ppc64 (64-bit big-endian POWER/PowerPC with AltiVec/VMX Extensions)

  • riscv (32-bit RISC-V)

  • riscv64 (64-bit RISC-V)

  • s390x (64-bit IBM System/390)

  • sparc (32-bit SPARC)

  • sparc64 (64-bit SPARCv9 or newer)

  • x86 (32-bit x86, 486-class or newer)

  • x86_64 (64-bit x86)

[Warning] Warning

Not all of the architectures listed here are supported by Adélie Linux at this time.

Default.  If the arch key is not present, the packages installed to the target will be the same CPU architecture as the system that executes the HorizonScript. Typically, this is the intended behaviour and the arch key will not need to be specified. However, if the HorizonScript will be executed on a different computer than the target — for example, if the target is an embedded system or single-board computer that is not capable of running the Horizon system — this key can be used to install packages compatible with the target.

Example. 

Example 2.7. The arch Key

arch ppc
                        

This sets the CPU architecture of the target computer to 32-bit PowerPC.


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 environment variable. Otherwise, this setting will be written to /etc/profile.d/00-language.sh for the definition of the LANG environment variable. 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. 

Example 2.8. The language Key — Simple Language

language cy
                        

This sets the language of the target computer to Welsh.


Example 2.9. The language Key — Language with Country Localisation

language fr_CA
                        

This sets the language of the target computer to Canadian French.


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. 

Example 2.10. The keymap Key

keymap fr
                        

This sets the keyboard layout of the target computer to French AZERTY.


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. 

Example 2.11. The firmware Key

firmware false
                        

This explicitly disables loading of firmware on the target computer.


Name.  netconfigtype

Purpose.  The netconfigtype key determines the desired network configuration type used on the target computer.

Format.  The netconfigtype key is a single string that describes the desired network configuration system used on the target computer. netconfigtype may appear at most once in a HorizonScript. Currently recognised network configuration systems for Horizon 1.0 are:

  1. netifrc — The netifrc system, as used by Adélie Linux

  2. eni — The /etc/network/interfaces system, as used by Alpine Linux

Default.  If no netconfigtype key is specified, the system will default to the netifrc configuration system.

Examples. 

Example 2.12. The netconfigtype Key — netifrc

netconfigtype netifrc
                        

This configures the target computer to use netifrc for network configuration.


Example 2.13. The netconfigtype Key — /etc/network/interfaces

netconfigtype eni
                        

This configures the target computer to use an /etc/network/interfaces file for network configuration.


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:

  1. 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).

  2. 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.

  3. The IP address. The value specified must be a valid IPv4 or IPv6 address.

  4. The prefix or network mask. The value must be either:

    1. A whole number in the range of 1-32 for IPv4 addresses, or 1-64 for IPv6 addresses.

    2. An IPv4 network mask, in the format octet.octet.octet.octet. This format cannot be used for IPv6 addresses.

  5. 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.

If network is true, then netaddress must appear at least once. If network is false, the network configuration specified in netaddress will be written to the target computer but will not be used during installation. netaddress 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.

Examples. 

Example 2.14. The netaddress Key — Simple DHCP

netaddress eth0 dhcp
                        

This configures the target computer to use DHCP on interface eth0.


Example 2.15. 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.


Name.  pppoe

Purpose.  The pppoe key configures a PPPoE link on a specified interface.

Format.  The pppoe key is a space-separated list of configuration information. The first item shall be the name of the Ethernet interface used to establish the link. Each additional item must be in the form key=value, where key is one of the following:

  1. mtu — The desired MTU of the interface.

  2. username — The username to use for authentication.

  3. password — The password/secret to use for authentication.

  4. lcp-echo-interval — The number of seconds between echo-requests to ensure the connection is still functioning.

  5. lcp-echo-failure — The number of failed echo-requests before the connection is determined to have a fault.

There shall be zero or one pppoe keys specified per interface. If an interface additionally has a netaddress specified for it, the netaddress configuration shall be ignored.

Default.  If the pppoe key is not specified, no PPPoE link will be established.

Example. 

Example 2.16. The pppoe Key

pppoe eth0 mtu=9120 username=awilfox password=fuzzball lcp-echo-interval=15 lcp-echo-failure=3
                        

This configures a PPPoE link on the interface eth0, with an MTU of 9120 and authentiation and LCP configuration as specified.


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 three 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. 

Example 2.17. The nameserver Key

nameserver 2620:fe::fe
                        

This configures the target computer to use Quad9's public resolver, 2620:fe::fe, for name queries.


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:

  1. 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).

  2. 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.

  3. 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).

  4. 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. 

Example 2.18. 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.


Example 2.19. 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.


Example 2.20. 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.


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. 

Example 2.21. 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.


Name.  version

Purpose.  The version key specifies the version of Adélie Linux being installed. The value of this key is used if repository is not specified to determine the repositories to use by default. If repository is provided, this key has no effect.

Format.  The version key is a string value which describes a version of Adélie Linux.

Default.  If the version key is not specified, the system will proceed as if the key had been specified with the value "stable".

Example. 

Example 2.22. The version Key

version 1.1
                        

This configures the target computer to install version 1.1 of Adélie Linux.


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. 

Example 2.23. 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.


Name.  svcenable

Purpose.  The svcenable key specifies a service to start up on system boot.

Format.  The svcenable key is a space-separate list which contains the name of a OpenRC service and an optional runlevel specification. The service file must be installed as part of a pkginstall key. svcenable may appear any number of times in a HorizonScript. If the runlevel is not specified, the default runlevel will be used.

Examples. 

Example 2.24. The svcenable Key — Enable SSH on Boot

svcenable sshd
                        

This configures the target computer to start the SSH daemon during system boot.


Example 2.25. The svcenable Key — Start udev on Boot

svcenable udev boot
svcenable udev-trigger boot
                        

This configures the target computer to start the udev and udev-trigger services during early boot, in the boot runlevel.


Example 2.26. The svcenable Key — Typical Desktop

svcenable dbus
svcenable elogind
svcenable sddm
                        

This configures the target computer to start up a display manager and its required daemons during system boot, enabling graphical logins.


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. 

Example 2.27. 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.


Name.  bootloader

Purpose.  The bootloader key specifies the bootloader configuration for the target computer.

Format.  The bootloader key is a space-separated list of the desired bootloader configuration. The first item, which is required, determines the block device that the bootloader will be installed on. The second item determines which bootloader to install. If the second value is not specified, or if the value is true, Horizon will install the platform's preferred bootloader. If the value is a string value, Horizon will attempt to install the specified bootloader. If the string value does not correspond to a bootloader available for the target computer, script execution will fail.

Default.  If no bootloader key is specified, no bootloader will be installed on the target computer and boot configuration must be performed externally.

Example. 

Example 2.28. The bootloader Key

bootloader /dev/sda
                        

This will configure the target computer with the platform's preferred bootloader installed to /dev/sda.


Name.  username

Purpose.  The username key specifies a user account to create on the target computer.

Format.  The username key is a string value, describing the user account's name. This name must be a valid Linux account name. username may be specified up to 255 times. It is invalid to specify the same account name more than once. It is invalid to specify the name of a system account.

Default.  If no username key is specified, no user accounts will be created on the system beyond the built-in system accounts. Only root will be able to log in.

Examples. 

Example 2.29. The username Key — Simple Usage

username awilfox
                        

This creates an account with name awilfox on the target computer.


Example 2.30. The username Key — Advanced Usage

username chris
username kayla
username meg
username steph
username amanada
                        

This creates five accounts on the target computer.


Name.  useralias

Purpose.  The useralias key provides the friendly name or alias of a user account on the target computer.

Format.  The useralias key is a space-separated tuple of two string values: the user account name, and the friendly name or alias to use. The friendly name is read to the end of the line and may contain spaces. useralias may appear up to once per username. It is invalid to specify more than one useralias for a given username. It is invalid to specify a useralias for an account that is not created by username.

Default.  If no useralias key is specified for a username, the alias "Adélie User" will be used.

Examples. 

Example 2.31. The useralias Key

useralias awilfox A. Wilcox
                        

This sets the friendly name of the awilfox account to A. Wilcox.


Name.  userpw

Purpose.  The userpw key specifies the passphrase to use for a given user account on the target computer.

Format.  The userpw key is a space-separated tuple of two string elements: the user account name, and the encrypted, SHA-512 or Blowfish hashed passphrase. It is invalid to specify a plaintext passphrase. userpw may appear up to once per username. It is invalid to specify more than one userpw for a given username. It is invalid to specify a userpw for an account that is not created by username.

Default.  If no userpw key is specified for a username, it will have no passphrase set. By default, this will prevent users from logging in to the account.

Example. 

Example 2.32. The userpw Key

userpw awilfox $6$UZJm/vBmVgyIdMZr$ppKEulz/HY0/e7RcXXujQbcqDXkUYgIqNEVPQJO6.le9kUpz8GvvRezY3ifqUUEwjhSo9tTOMG7lhqjn8gGpH0
                        

This sets the passphrase of the awilfox account to My Passphrase. (Please do not use this passphrase.)


Name.  usericon

Purpose.  The usericon key specifies a icon used to identify a given user account on the target computer.

Format.  The usericon key is a space-separated tuple of two string elements: the user account name, and a path to the icon. The icon must be in JPEG, PNG, TGA, or TIFF format. The path must be an absolute path accessible from the installation environment, or a supported URL. usericon may appear up to once per username. It is invalid to specify more than one usericon for a given username. It is invalid to specify a usericon for an account that is not created by username.

Default.  If no usericon key is specified for a username, a default silhouette icon will be used for that account.

Example. 

Example 2.33. The usericon Key

usericon awilfox /usr/share/user-manager/avatars/circles/Cat.png
                        

This sets the icon of the awilfox account to the default Cat avatar.


Name.  usergroups

Purpose.  The usergroups key specifies group membership for a given user account on the target computer.

Format.  The usergroups key is a space-separated tuple of two string elements: the user account name, and a comma-separated list of groups of which the account should become a member. usergroups may appear at least once per username. Each usergroups key for a given username appends to an existing list, if any. It is invalid to specify the same group more than once for a given username. It is invalid to specify more than 16 groups for a given username across all usergroups specified for it.

Default.  If no usergroups is specified for a given username, it will be added to the users group. If it is given, the users group must be explicitly specified if desired.

Examples. 

Example 2.34. The usergroups Key — Simple Usage

usergroups awilfox users,wheel
                        

This specifies that the awilfox account will become a member of the groups users and wheel on the target computer.


Example 2.35. The usergroups Key — Advanced Usage

usergroups chris disk,lp,wheel,floppy,audio,cdrom,video,games,cdrw,usb,users
usergroups kayla lp,audio,cdrom,video,games,users
usergroups meg lp,audio,cdrom,video,games,users
usergroups steph lp,audio,cdrom,video,games,users
usergroups amanda lp,audio,cdrom,video,games,users
                        

This specifies that the chris account will become an administrative account and have access to most peripherals of the system, while the rest will have access to printers, sound, optical storage, graphics, and the ability to play games.


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.

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.

Name.  diskid

Purpose.  The diskid key specifies a substring of a disk's identification string. The system matches this string to the specified block device's identification string to ensure that the proper disk is partitioned.

Format.  The diskid key is a space-separated tuple of values that contains exactly two string elements: a valid block device file name, and the substring of its identification string. The second element is read to the end of the string, so it may contain further spaces. diskid may appear up to one time per block device file name. It is invalid to specify more than one diskid for the same block device.

Default.  If the diskid key is not specified for a block device, the system will not be able to verify that the block device is the intended target of partitioning commands.

Examples. 

Example 2.36. The diskid Key — Verify Manufacturer of Hard Disk

diskid /dev/sda HITACHI
                        

This ensures that the identification string of the disk at /dev/sda contains the string 'HITACHI'.


Example 2.37. The diskid Key — Verify Model of NVMe Device

diskid /dev/nvme0n1 WDC WDS512G1X0C-00ENX0
                        

This ensures that the identification string of the NVMe device at /dev/nvme0n1 contains the string 'WDC WDS512G1X0C-00ENX0'.


Name.  disklabel

Purpose.  The disklabel key specifies the type of partitioning a disk will use.

Format.  The disklabel key is a space-separated tuple of values that contains exactly two string elements: a valid block device file name, and the type of disk label to use. Valid disk labels are:

  1. mbr — Master Boot Record (MBR)

  2. gpt — GUID Partition Table (GPT)

  3. apm — Apple Partition Map (APM)

disklabel may appear up to once per block device file name. It is invalid to specify more than one disklabel for the same block device.

Default.  If the disklabel key is not specified for a block device, the existing disk label will be used. If no disk label is currently written to the device, the device will not contain a disk label.

Examples. 

Example 2.38. The disklabel Key — Simple Usage

disklabel /dev/sda mbr
                        

This erases any present disk label on the block device at /dev/sda and creates a new MBR disk label.


Example 2.39. The disklabel Key — Multiple Disks

disklabel /dev/sda apm
disklabel /dev/sdb gpt
disklabel /dev/nvme0n1 gpt
                        

This erases any present disk labels on the block devices /dev/sda, /dev/sdb, and /dev/nvme0n1. The system will then create a new APM disk label on /dev/sda, and new GPT disk labels on each of /dev/sdb and /dev/nvme0n1. This example would allow you to use mass storage (greater than 2 TB) on a Power Mac G5 while retaining OpenFirmware boot compatibility on the first disk.


Name.  partition

Purpose.  The partition key specifies a new partition to be created on a block device.

Format.  The partition key is a space-separated tuple of values that contains either three or four elements: a valid block device file name, the partition number to create, the size of the new partition as specified in the section called “Sizing”, and optionally a type code for the partition. Valid type codes are:

  1. boot — Marks the partition as bootable. On MBR disk labels, this enables the Bootable flag. On APM disk labels, this sets the partition type to Apple_Bootstrap. On GPT disk labels, this sets the partition's type to BIOS Boot.

  2. esp — Marks the partition as an EFI System Partition (ESP). This type is only valid on GPT disk labels.

  3. bios — Marks the partition as a BIOS Boot partition. This type is only valid on GPT disk labels.

  4. prep — Marks the partition as a PowerPC Boot partition. This type is only valid on MBR disk labels.

partition may appear many times per block device file name; the exact maximum depend on the disk label in use on the block device. It is invalid to specify a partition for a partition number that already exists on the block device. It is invalid to specify a partition for a block device that does not have a disk label supported by Horizon.

Default.  If no partition key is specified for a given block device, then the partition table on that block device is not modified.

Examples. 

Example 2.40. The partition Key — Simple Usage

partition /dev/sda 1 40M boot
partition /dev/sda 2 fill
                        

This configures /dev/sda to contain a 40 MiB boot partition, and uses the rest of the disk as a single data partition.


Example 2.41. The partition Key — Advanced Usage

partition /dev/sda 1 1G boot
partition /dev/sda 2 20%
partition /dev/sda 3 40%
partition /dev/sda 4 fill
                        

This configures /dev/sda to contain a 1 GiB boot partition, a second partition using 20% of the disk's total size, a third partition using 40% of the disk's total size, and a fourth partition that utilises the rest of the disk.


Name.  lvm_pv

Purpose.  The lvm_pv key specifies a block device to use as a LVM physical volume.

Format.  The lvm_pv key is a string value which must describe a path to a valid block device. This is typically either a whole disk or a partition on a disk. lvm_pv may be specified up to once per block device specification. If an lvm_pv key is specified for both a block device and an underlying partition already extant on the block device, system behaviour is undefined.

Default.  If no lvm_pv key is specified, no LVM physical volume will be created by the system.

Examples. 

Example 2.42. The lvm_pv Key — Whole Disk LVM

lvm_pv /dev/sda
                        

This configures the entire block device at /dev/sda to be an LVM physical volume. Any existing data on the specified disk will be destroyed.


Example 2.43. The lvm_pv Key — LVM Partition

disklabel /dev/sda gpt
partition /dev/sda 1 4M boot
partition /dev/sda 2 fill
lvm_pv /dev/sda2
                        

This configures the block device at /dev/sda with a new GPT disk label, creates a 4 MiB BIOS Boot partition, and then uses the rest of the disk as an LVM physical volume.


Name.  lvm_vg

Purpose.  The lvm_vg key specifies parameters for creating a new LVM volume group on the target computer.

Format.  The lvm_vg key is a space-separated tuple of exactly two string values: a path to a valid block device containing an LVM physical volume, and a valid LVM volume group name. A volume group will be created on the specified LVM physical volume with the specified name. It is invalid to specify a block device that does not contain an LVM physical volume.

Default.  If no lvm_vg key is specified, no LVM volume groups will be created on the target computer.

Example. 

Example 2.44. The lvm_vg Key

lvm_vg /dev/sda2 elaine
                        

This creates a new LVM volume group named elaine on the LVM physical volume /dev/sda2.


Name.  lvm_lv

Purpose.  The lvm_lv key specifies parameters for creating a new LVM logical volume on the target computer.

Format.  The lvm_lv key is a space-separated tuple of exactly three values: the name of an extant LVM volume group, the name of the LVM logical volume to create, and the size of the new LVM logical volume as specified in the section called “Sizing”. The name of the new LVM logical volume must be a valid logical volume name. It is invalid to specify a logical volume size larger than the available space in the volume group.

Default.  If no lvm_lv key is specified, no LVM logical volumes will be created on the target computer.

Examples. 

Example 2.45. The lvm_lv Key

lvm_lv elaine root fill
                        

This creates a new LVM logical volume named root on the LVM volume group elaine, using all available space in the volume group.


Name.  encrypt

Purpose.  The encrypt key specifies block devices to encrypt with LUKS.

Format.  The encrypt key has two forms. The first form is a string value which must be a path to a valid block device. The second form is a tuple of two string values which are a path to a valid block device, and the passphrase to use to encrypt the volume.

[Warning] Warning

The passphrase to encrypt the volume should not be provided if a non-encrypted network transport is used to transfer the HorizonScript to the target computer. This could expose the passphrase to attackers.

The passphrase will be read to the end of the line, so it may contain spaces if desired. If no passphrase is specified, the system will interactively prompt for a passphrase during the installation. There is no time out for entering a passphrase. encrypt may be specified up to once per block device. It is invalid to specify an encrypt key more than once for the same block device.

Default.  If no encrypt key is specified, no LUKS containers will be created. If no passphrase is specified in an encrypt key, the system will interactively prompt for one.

Examples. 

Example 2.46. The encrypt Key — Prompt for Passphrase

encrypt /dev/elaine/root
                        

This configures the block device at /dev/elaine/root to use LUKS, and prompts the installing technician for a passphrase.


Example 2.47. The encrypt Key — Use Plaintext Passphrase

encrypt /dev/elaine/home oh. so. secret.
                        

This configures the block device at /dev/elaine/home to use LUKS with the passphrase oh. so. secret. in plaintext.


Name.  fs

Purpose.  The fs key specifies file systems to create on the target computer.

Format.  The fs key is a space-separated tuple of two string elements: a path to a valid block device, and the type of file system to use. Valid file systems are:

  1. ext2 — The ext2 file system, a non-journaled Linux filesystem.

  2. ext3 — The ext3 file system, a journaled Linux filesystem.

  3. ext4 — The ext4 file system, a journaled Linux filesystem.

  4. hfs+ — The HFS Plus file system, a non-journaled filesystem from Apple used for boot partitions on Macintosh computers.

  5. jfs — The JFS file system, a journaled filesystem from IBM.

  6. xfs — The XFS file system, a journaled filesystem orginally developed by SGI.

  7. vfat — The FAT32 file system, a non-journaled filesystem used for EFI System Partitions on computers with EFI firmware.

  8. swap — Swap space, used for virtual memory.

fs may be specified up to once per block device. It is invalid to specify fs more than once for the same block device.

Default.  If no fs key is specified, no file systems will be created on the target computer.

Examples. 

Example 2.48. The fs Key

fs /dev/elaine/root ext4
fs /dev/elaine/home xfs
                        

This creates a new ext4 file system on the block device at /dev/elaine/root, and creates a new XFS file system on /dev/elaine/home.


Name.  mount

Purpose.  The mount key describes the filesystems and mountpoints to use on the target computer.

Format.  The mount key is a space-separated tuple of two or three string elements: a path to a valid block device, the mountpoint on the target computer, and optionally mounting options. The mountpoint must start with /. Valid mounting options depend on the file system chosen, but typically include options such as noatime, user, and so on. See the mount manpage for the file system you are using for more information on mounting options. Mounting options are separated with commas. Mounting options will be used in the installation environment and additionally saved to the target computer's /etc/fstab file. mount must be specified at least once, for the root (/) partition. It is invalid to specify mount more than once for the same block device. It is invalid to specify mount more than once for the same mountpoint.

Examples. 

Example 2.49. The mount Key

mount /dev/elaine/root /
mount /dev/elaine/home /home noquota,wsync
                        

The filesystem at /dev/elaine/root will be mounted at /. The filesystem at /dev/elaine/home will be mounted at /home, with the noquota and wsync options.