path: root/devel/script/2_keys.xml

<?xml version="1.0" encoding="utf-8"?>
<chapter label="2" id="keys">
    <title>HorizonScript Keys</title>
    <section id="key_intro">
        <title>Introduction</title>
        <para>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 <firstterm>key</firstterm>s, which is a logical unit of a value.</para>
        <para>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.</para>
    </section>
    <section id="reqd_keys">
        <title>Required Keys</title>
        <para>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.</para>
        <section id="network">
            <title><literal>network</literal></title>
            <formalpara id="network.name">
                <title>Name</title>
                <para><literal>network</literal></para>
            </formalpara>
            <formalpara id="network.purpose">
                <title>Purpose</title>
                <para>The <literal>network</literal> key determines if the target computer will support networking or not.  If the value is <literal>true</literal>, the computer will support networking, and at least one <literal>netaddress</literal> key will then be required.</para>
            </formalpara>
            <formalpara id="network.format">
                <title>Format</title>
                <para>The <literal>network</literal> key is a Boolean value &mdash; valid values are <literal>true</literal> and <literal>false</literal>.  <literal>network</literal> must appear exactly once in a HorizonScript.</para>
            </formalpara>
            <formalpara id="network.example">
                <title>Example</title>
                <para>
                    <example>
                        <title>The <literal>network</literal> Key</title>
                        <programlisting>
network true
                        </programlisting>
                        <para>This enables networking for the target computer.</para>
                    </example>
                </para>
            </formalpara>
        </section>
        <section id="hostname">
            <title><literal>hostname</literal></title>
            <formalpara id="hostname.name">
                <title>Name</title>
                <para><literal>hostname</literal></para>
            </formalpara>
            <formalpara id="hostname.purpose">
                <title>Purpose</title>
                <para>The <literal>hostname</literal> 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.</para>
            </formalpara>
            <formalpara id="hostname.format">
                <title>Format</title>
                <para>The <literal>hostname</literal> 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.  <literal>hostname</literal> must appear exactly once in a HorizonScript.</para>
            </formalpara>
            <formalpara id="hostname.examples">
                <title>Examples</title>
                <para>
                    <example>
                        <title>The <literal>hostname</literal> Key &mdash; Setting a Host Name</title>
                        <programlisting>
hostname gwyn
                        </programlisting>
                        <para>This sets the hostname of the target computer to <literal>gwyn</literal>.</para>
                    </example>
                    <example>
                        <title>The <literal>hostname</literal> Key &mdash; Setting a Host Name and Domain Name</title>
                        <programlisting>
hostname gwyn.foxkit.internal
                        </programlisting>
                        <para>This sets the hostname of the target computer to <literal>gwyn.foxkit.internal</literal>.</para>
                    </example>
                </para>
            </formalpara>
        </section>
        <section id="pkginstall">
            <title><literal>pkginstall</literal></title>
            <formalpara id="pkginstall.name">
                <title>Name</title>
                <para><literal>pkginstall</literal></para>
            </formalpara>
            <formalpara id="pkginstall.purpose">
                <title>Purpose</title>
                <para>The <literal>pkginstall</literal> key lists the packages that will be installed on the target computer.</para>
            </formalpara>
            <formalpara id="pkginstall.format">
                <title>Format</title>
                <para>The <literal>pkginstall</literal> is a space-separated list of APK packages.  They must be available in the repositories used during the installation process.  <literal>pkginstall</literal> must appear at least once in a HorizonScript.  There is no limit to the number of times <literal>pkginstall</literal> may be specified; each one will append to the list of packages to install.</para>
            </formalpara>
            <formalpara id="pkginstall.examples">
                <title>Examples</title>
                <para>
                    <example>
                        <title>The <literal>pkginstall</literal> Key &mdash; Simple Usage</title>
                        <programlisting>
pkginstall adelie-base-posix kde x11
                        </programlisting>
                        <para>This installs the <literal><package>adelie-base-posix</package></literal>, <literal><package>kde</package></literal>, and <literal><package>x11</package></literal> packages on the target computer.</para>
                    </example>
                    <example>
                        <title>The <literal>pkginstall</literal> Key &mdash; Multiple Invocations</title>
                        <programlisting>
pkginstall adelie-base-posix
pkginstall x11 i3wm
pkginstall claws-mail
                        </programlisting>
                        <para>This installs the <literal><package>adelie-base-posix</package></literal>, <literal><package>x11</package></literal>, <literal><package>i3wm</package></literal>, and <literal><package>claws-mail</package></literal> packages on the target computer.  This advanced usage may be useful if you use a templating engine to generate HorizonScript files.</para>
                    </example>
                </para>
            </formalpara>
        </section>
    </section>
    <section id="opt_keys">
        <title>Optional Keys</title>
        <para>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.</para>
        <section id="language">
            <title><literal>language</literal></title>
            <formalpara id="language.name">
                <title>Name</title>
                <para><literal>language</literal></para>
            </formalpara>
            <formalpara id="language.purpose">
                <title>Purpose</title>
                <para>The <literal>language</literal> key determines the default natural language for the target computer.  The value of this key will be used to configure the <envar>LANG</envar> and <envar>LC_ALL</envar> environment variables, in addition to installing language packs for certain software.</para>
            </formalpara>
            <formalpara id="language.format">
                <title>Format</title>
                <para>The <literal>language</literal> key is a string value that specifies a valid locale code.  A locale code must match one of the following formats: <replaceable>xx</replaceable>, or <replaceable>xx</replaceable><literal>_</literal><replaceable>YY</replaceable>, or <replaceable>xx</replaceable><literal>_</literal><replaceable>YY</replaceable><literal>.UTF-8</literal>, where <replaceable>xx</replaceable> is a valid ISO 639-1 language code, and <replaceable>YY</replaceable> is a valid ISO 3166-1 country code.  <literal>language</literal> may appear at most once in a HorizonScript.</para>
            </formalpara>
            <formalpara id="language.default">
                <title>Default</title>
                <para>If the <literal>language</literal> key is not present, no setting will be defined for the <envar>LANG</envar> or <envar>LC_ALL</envar> 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 <emphasis role="italics">de facto</emphasis> language of software engineering, this implies all software will run in English.</para>
            </formalpara>
            <formalpara id="language.examples">
                <title>Examples</title>
                <para>
                    <example>
                        <title>The <literal>language</literal> Key &mdash; Simple Language</title>
                        <programlisting>
language cy
                        </programlisting>
                        <para>This sets the language of the target computer to Welsh.</para>
                    </example>
                    <example>
                        <title>The <literal>language</literal> Key &mdash; Language with Country Localisation</title>
                        <programlisting>
language fr_CA
                        </programlisting>
                        <para>This sets the language of the target computer to Canadian French.</para>
                    </example>
                </para>
            </formalpara>
        </section>
        <section id="keymap">
            <title><literal>keymap</literal></title>
            <formalpara id="keymap.name">
                <title>Name</title>
                <para><literal>keymap</literal></para>
            </formalpara>
            <formalpara id="keymap.purpose">
                <title>Purpose</title>
                <para>The <literal>keymap</literal> key determines the keyboard layout used for input on the target computer.</para>
            </formalpara>
            <formalpara id="keymap.format">
                <title>Format</title>
                <para>The <literal>keymap</literal> key is a string value that specifies the name of a keyboard layout.  Valid keyboard layouts are listed in <filename>/etc/console-setup/ckb/rules/xorg.lst</filename> under the <literal>! layout</literal> heading.  <literal>keymap</literal> may appear at most once in a HorizonScript.</para>
            </formalpara>
            <formalpara id="keymap.default">
                <title>Default</title>
                <para>If the <literal>keymap</literal> 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.</para>
            </formalpara>
            <formalpara id="keymap.example">
                <title>Example</title>
                <para>
                    <example>
                        <title>The <literal>keymap</literal> Key</title>
                        <programlisting>
keymap fr
                        </programlisting>
                        <para>This sets the keyboard layout of the target computer to French AZERTY.</para>
                    </example>
                </para>
            </formalpara>
        </section>
        <section id="firmware">
            <title><literal>firmware</literal></title>
            <formalpara id="firmware.name">
                <title>Name</title>
                <para><literal>firmware</literal></para>
            </formalpara>
            <formalpara id="firmware.purpose">
                <title>Purpose</title>
                <para>The <literal>firmware</literal> key determines if the target computer will load potentially insecure, proprietary firmware.</para>
            </formalpara>
            <formalpara id="firmware.format">
                <title>Format</title>
                <para>The <literal>firmware</literal> key is a Boolean value &mdash; valid values are <literal>true</literal> and <literal>false</literal>.  <literal>firmware</literal> may appear at most once in a HorizonScript.</para>
            </formalpara>
            <formalpara id="firmware.default">
                <title>Default</title>
                <para>If the <literal>firmware</literal> 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.</para>
            </formalpara>
            <formalpara id="firmware.example">
                <title>Example</title>
                <para>
                    <example>
                        <title>The <literal>firmware</literal> Key</title>
                        <programlisting>
firmware false
                        </programlisting>
                        <para>This explicitly disables loading of firmware on the target computer.</para>
                    </example>
                </para>
            </formalpara>
        </section>
        <section id="netaddress">
            <title><literal>netaddress</literal></title>
            <formalpara id="netaddress.name">
                <title>Name</title>
                <para><literal>netaddress</literal></para>
            </formalpara>
            <formalpara id="netaddress.purpose">
                <title>Purpose</title>
                <para>The <literal>netaddress</literal> key determines the network configuration used on the target computer.</para>
            </formalpara>
            <formalpara id="netaddress.format">
                <title>Format</title>
                <para>The <literal>netaddress</literal> key is a space-separated list of network configuration information:
                    <orderedlist id="netaddress.format.items">
                        <listitem><para>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).</para></listitem>
                        <listitem><para>The addressing type.  Valid values are <literal>dhcp</literal> for DHCP v4 and v6, <literal>slaac</literal> for IPv6 Stateless Automatic Address Configuration, and <literal>static</literal> for Administrator-specified addressing.  The list must end here unless the address type specified is <literal>static</literal>.  Any additional items constitute a configuration error and an invalid HorizonScript.</para></listitem>
                        <listitem><para>The IP address.  The value specified must be a valid IPv4 or IPv6 address.</para></listitem>
                        <listitem><para>The prefix or network mask.  The value must be either:
                                <orderedlist id="netaddress.format.prefix_types">
                                    <listitem><para>A whole number in the range of 1-32 for IPv4 addresses, or 1-64 for IPv6 addresses.</para></listitem>
                                    <listitem><para>An IPv4 network mask, in the format <literal><replaceable>octet</replaceable>.<replaceable>octet</replaceable>.<replaceable>octet</replaceable>.<replaceable>octet</replaceable></literal>.</para></listitem>
                                </orderedlist>
                        </para></listitem>
                        <listitem><para>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.</para></listitem>
                    </orderedlist>
                    <literal>netaddress</literal> must not appear unless <literal>network</literal> is <literal>true</literal>.  If <literal>network</literal> is <literal>true</literal>, then <literal>netaddress</literal> must appear at least once, and may appear up to 255 times per interface.
                </para>
            </formalpara>
            <formalpara id="netaddress.default">
                <title>Default</title>
                <para>There is no default for this key.  It is invalid to enable networking and not provide at least one <literal>netaddress</literal> key.</para>
            </formalpara>
            <formalpara id="netaddress.example">
                <title>Example</title>
                <para>
                    <example>
                        <title>The <literal>netaddress</literal> Key &mdash; Simple DHCP</title>
                        <programlisting>
netaddress eth0 dhcp
                        </programlisting>
                        <para>This configures the target computer to use DHCP on interface <literal>eth0</literal>.</para>
                    </example>
                    <example>
                        <title>The <literal>netaddress</literal> Key &mdash; Static Addressing</title>
                        <programlisting>
netaddress eth0 2001:db8::1337 64 2001:db8::1
netaddress eth0 198.51.100.37 24 198.51.100.1
                        </programlisting>
                        <para>This configures the target computer to use the addresses <literal>2001:db::1337/64</literal> and <literal>198.51.100.37/24</literal> on interface <literal>eth0</literal>.  The default gateways are <literal>2001:db::1</literal> and <literal>198.51.100.1</literal>.</para>
                    </example>
                </para>
            </formalpara>
        </section>
        <section id="nameserver">
            <title><literal>nameserver</literal></title>
            <formalpara id="nameserver.name">
                <title>Name</title>
                <para><literal>nameserver</literal></para>
            </formalpara>
            <formalpara id="nameserver.purpose">
                <title>Purpose</title>
                <para>The <literal>nameserver</literal> key determines the DNS server used for name queries on the target computer.</para>
            </formalpara>
            <formalpara id="nameserver.format">
                <title>Format</title>
                <para>The <literal>nameserver</literal> key takes either an IPv4 address or IPv6 address.  Any other value is invalid.  The <literal>nameserver</literal> may appear up to four times in a HorizonScript, or be omitted.  It is valid to specify <literal>nameserver</literal> even if <literal>network</literal> is <literal>false</literal>, but name queries will not function properly without a network configuration.</para>
            </formalpara>
            <formalpara id="nameserver.default">
                <title>Default</title>
                <para>If the <literal>nameserver</literal> key is not specified, name queries requiring the DNS will not succeed on the target computer.</para>
            </formalpara>
            <formalpara id="nameserver.example">
                <title>Example</title>
                <para>
                    <example>
                        <title>The <literal>nameserver</literal> Key</title>
                        <programlisting>
nameserver 2620:fe::fe
                        </programlisting>
                        <para>This configures the target computer to use <ulink url="https://www.quad9.net/about/">Quad9</ulink>'s public resolver, <literal>2620:fe::fe</literal>, for name queries.</para>
                    </example>
                </para>
            </formalpara>
        </section>
        <section id="netssid">
            <title><literal>netssid</literal></title>
            <formalpara id="netssid.name">
                <title>Name</title>
                <para><literal>netssid</literal></para>
            </formalpara>
            <formalpara id="netssid.purpose">
                <title>Purpose</title>
                <para>The <literal>netssid</literal> key determines the wireless networking configuration on the target computer.</para>
            </formalpara>
            <formalpara id="netssid.format">
                <title>Format</title>
                <para>The <literal>netssid</literal> is a space-separated list of wireless networking configuration information:
                    <orderedlist id="netssid.format.items">
                        <listitem><para>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).</para></listitem>
                        <listitem><para>The SSID name to connect to.  This must be a string value enclosed by ASCII double-quotes (<literal>"</literal>).  System behaviour is undefined if the SSID name contains an ASCII double-quote.</para></listitem>
                        <listitem><para>The security type of the SSID.  Valid values are <literal>none</literal> for an open access point, <literal>wep</literal> for a WEP passphrase, and <literal>wpa</literal> for a WPA pre-shared key (PSK).</para></listitem>
                        <listitem><para>If the security type is not <literal>none</literal>, 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.</para></listitem>
                    </orderedlist>
                </para>
            </formalpara>
            <formalpara id="netssid.default">
                <title>Default</title>
                <para>If the <literal>netssid</literal> key is not specified, no wireless network configuration will be present on the target computer.</para>
            </formalpara>
            <formalpara id="netssid.examples">
                <title>Examples</title>
                <para>
                    <example>
                        <title>The <literal>netssid</literal> Key &mdash; Open Network</title>
                        <programlisting>
netssid wlan0 "h" none
                        </programlisting>
                        <para>This configures the target computer to connect to the access point with name <literal>h</literal>, with no security.</para>
                    </example>
                    <example>
                        <title>The <literal>netssid</literal> Key &mdash; WEP Network</title>
                        <programlisting>
netssid wlan0 "Hophop" wep omgitsarabbit
                        </programlisting>
                        <para>This configures the target computer to connect to the access point with name <literal>Hophop</literal>, with the WEP passphrase <literal>omgitsarabbit</literal>.</para>
                    </example>
                    <example>
                        <title>The <literal>netssid</literal> Key &mdash; WPA2 Network</title>
                        <programlisting>
netssid wlan0 "The New Fox 5G" wpa shh sekrit
                        </programlisting>
                        <para>This configures the target computer to connect to the access point with name <literal>The New Fox 5G</literal>, with the WPA PSK <literal>shh sekrit</literal>.</para>
                    </example>
                </para>
            </formalpara>
        </section>
        <section id="timezone">
            <title><literal>timezone</literal></title>
            <formalpara id="timezone.name">
                <title>Name</title>
                <para><literal>timezone</literal></para>
            </formalpara>
            <formalpara id="timezone.purpose">
                <title>Purpose</title>
                <para>The <literal>timezone</literal> key determines the local time zone on the target computer.</para>
            </formalpara>
            <formalpara id="timezone.format">
                <title>Format</title>
                <para>The <literal>timezone</literal> 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: <command>find /usr/share/zoneinfo</command>.  <literal>timezone</literal> may appear at most once in a HorizonScript.</para>
            </formalpara>
            <formalpara id="timezone.default">
                <title>Default</title>
                <para>If the <literal>timezone</literal> key is not specified, the target computer will use UTC (Universal Coordinated Time) as its time zone.</para>
            </formalpara>
            <formalpara id="timezone.example">
                <title>Example</title>
                <para>
                    <example>
                        <title>The <literal>timezone</literal> Key</title>
                        <programlisting>
timezone Africa/Nairobi
                        </programlisting>
                        <para>This configures the target computer to use East Africa Time, as observed in Nairobi, Kenya, for the local time zone.</para>
                    </example>
                </para>
            </formalpara>
        </section>
        <section id="repository">
            <title><literal>repository</literal></title>
            <formalpara id="repository.name">
                <title>Name</title>
                <para><literal>repository</literal></para>
            </formalpara>
            <formalpara id="repository.purpose">
                <title>Purpose</title>
                <para>The <literal>repository</literal> 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 <filename>/etc/apk/repository</filename> file on the target computer.</para>
            </formalpara>
            <formalpara id="repository.format">
                <title>Format</title>
                <para>The <literal>repository</literal> key is a string value which must describe either an absolute local path or a HTTP or HTTPS location on the network.  <literal>repository</literal> may appear up to ten times in a HorizonScript, or be omitted.</para>
            </formalpara>
            <formalpara id="repository.default">
                <title>Default</title>
                <para>If the <literal>repository</literal> key is not specified, the default repositories for Adélie Linux will be used:
                    <itemizedlist id="repository.default.repos">
                        <listitem><para>https://distfiles.adelielinux.org/adelie/$VERSION/system</para></listitem>
                        <listitem><para>https://distfiles.adelielinux.org/adelie/$VERSION/user</para></listitem>
                    </itemizedlist>
                    where <replaceable>$VERSION</replaceable> is the version of Adélie Linux being installed.  Additionally, if the <literal>firmware</literal> key is specified and set to <literal>true</literal>, the <literal>https://distfiles.apkfission.net/adelie-$VERSION/nonfree</literal> repository will be added.  If <literal>repository</literal> is specified, <emphasis>none of these repositories will be used unless manually specified</emphasis>.
                </para>
            </formalpara>
            <formalpara id="repository.example">
                <title>Example</title>
                <para>
                    <example>
                        <title>The <literal>repository</literal> Key</title>
                        <programlisting>
repository https://mirrors.servercentral.com/adelie/1.0/system
repository https://mirrors.servercentral.com/adelie/1.0/user
                        </programlisting>
                        <para>This configures the target computer to use the Server Central mirrors.</para>
                    </example>
                </para>
            </formalpara>
        </section>
        <section id="signingkey">
            <title><literal>signingkey</literal></title>
            <formalpara id="signingkey.name">
                <title>Name</title>
                <para><literal>signingkey</literal></para>
            </formalpara>
            <formalpara id="signingkey.purpose">
                <title>Purpose</title>
                <para>The <literal>signingkey</literal> key specifies a key to trust for APK package repositories.</para>
            </formalpara>
            <formalpara id="signingkey.format">
                <title>Format</title>
                <para>The <literal>signingkey</literal> 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 <literal>signingkey</literal>.  <literal>signingkey</literal> may appear up to ten times in a HorizonScript, or be omitted.</para>
            </formalpara>
            <formalpara id="signingkey.default">
                <title>Default</title>
                <para>If the <literal>signingkey</literal> key is not specified, the Adélie Linux repository signing key will be used.  Additionally, if the <literal>firmware</literal> key is specified and set to <literal>true</literal>, the APK Fission signing key will be used.  If <literal>signingkey</literal> is specified, <emphasis>none of these signing keys will be trusted unless manually specified</emphasis>.</para>
            </formalpara>
            <formalpara id="signingkey.example">
                <title>Example</title>
                <para>
                    <example>
                        <title>The <literal>signingkey</literal> Key</title>
                        <programlisting>
signingkey /etc/apk/keys/packages@adelielinux.org.pub
signingkey https://packages/builder@ourcompany.net.pub
                        </programlisting>
                        <para>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 <literal>https://packages/builder@ourcompany.net.pub</literal>.</para>
                    </example>
                </para>
            </formalpara>
        </section>
    </section>
</chapter>