From 0dd4ee7bae15e768ddacfa37ef11e27c721d7c04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Kr=C3=A1tk=C3=BD?= Date: Wed, 25 Oct 2023 14:40:33 +0200 Subject: [PATCH] Language and formatting review of the Reference section. --- doc/.custom_wordlist.txt | 4 +- doc/reference/autoinstall-reference.rst | 520 +++++++++--------------- doc/reference/autoinstall-schema.rst | 30 +- doc/reference/index.rst | 8 +- doc/reuse/substitutions.txt | 4 +- 5 files changed, 222 insertions(+), 344 deletions(-) diff --git a/doc/.custom_wordlist.txt b/doc/.custom_wordlist.txt index edeefb120..266896eb2 100644 --- a/doc/.custom_wordlist.txt +++ b/doc/.custom_wordlist.txt @@ -17,6 +17,7 @@ LUKS LV LVM LinuxONE +Mantic MiB NIC Netplan @@ -36,7 +37,7 @@ UEFI URI Zdev amd -authorized-keys +authorized autoinstall autoinstaller autoinstalls @@ -51,6 +52,7 @@ debian-installer el flavor geoip +geolocation globbing hostname iSCSI diff --git a/doc/reference/autoinstall-reference.rst b/doc/reference/autoinstall-reference.rst index a7e78f163..66f05db3c 100644 --- a/doc/reference/autoinstall-reference.rst +++ b/doc/reference/autoinstall-reference.rst @@ -1,55 +1,49 @@ .. _ai: Autoinstall configuration reference manual -****************************************** +========================================== -The autoinstall file is YAML. At top level it must be a mapping containing the -keys described in this document. Unrecognised keys are ignored. +The autoinstall file uses the YAML format. At the top level, it must be a mapping containing the keys described in this document. Unrecognised keys are ignored. .. _ai-schema: Schema -====== +------ -Autoinstall configurations are -:doc:`validated against a JSON schema` before they are +Autoinstall configurations are :doc:`validated against a JSON schema ` before they are used. .. _ai-command-lists: Command lists -============= +------------- -Several configuration keys are lists of commands to be executed. Each command can be -a string (in which case it is executed via ``sh -c``) or a list, in which case -it is executed directly. Any command exiting with a non-zero return code is -considered an error and aborts the installation (except for error-commands, where -it is ignored). +Several configuration keys are lists of commands to be executed. Each command can be a string (in which case it is executed via :command:`sh -c`) or a list, in which case it is executed directly. Any command exiting with a non-zero return code is considered an error and aborts the installation (except for error-commands, where it is ignored). .. _ai-top-level-keys: Top-level keys -============== +-------------- .. _ai-version: version -------- +~~~~~~~ * **type:** integer * **default:** no default -A future-proofing configuration file version field. Currently this must be "1". +A future-proofing configuration file version field. Currently, this must be ``1``. .. _ai-interactive-sections: interactive-sections --------------------- +~~~~~~~~~~~~~~~~~~~~ * **type:** list of strings * **default:** [] -A list of configuration keys to still show in the UI. For example: +A list of configuration keys to still show in the user interface (UI). For example: .. code-block:: yaml @@ -60,39 +54,29 @@ A list of configuration keys to still show in the UI. For example: username: ubuntu password: $crypted_pass -This example stops on the network screen and allows the user to change the defaults. If -a value is provided for an interactive section, it is used as the default. +This example stops on the network screen and allows the user to change the defaults. If a value is provided for an interactive section, it is used as the default. -You can use the special section name of ``*`` to indicate that the installer -should ask all the usual questions -- in this case, the :file:`autoinstall.yaml` -file is not really an "autoinstall" file at all, instead just a way to change -the defaults in the UI. +You can use the special section name of ``*`` to indicate that the installer should ask all the usual questions -- in this case, the :file:`autoinstall.yaml` file is an autoinstall file. It just provides a way to change the defaults in the UI. -Not all configuration keys correspond to screens in the UI. This documentation -indicates if a given section can be interactive or not. +Not all configuration keys correspond to screens in the UI. This documentation indicates if a given section can be interactive or not. -If there are any interactive sections at all, the :ref:`ai-reporting` key is -ignored. +If there are any interactive sections at all, the :ref:`ai-reporting` key is ignored. .. _ai-early-commands: early-commands --------------- +~~~~~~~~~~~~~~ * **type:** :ref:`command list` * **default:** no commands * **can be interactive:** no -A list of shell commands to invoke as soon as the installer starts, in -particular before probing for block and network devices. The autoinstall -configuration is available at :file:`/autoinstall.yaml` (irrespective of how it was -provided) and the file will be re-read after the ``early-commands`` have run to -allow them to alter the configuration if necessary. +A list of shell commands to invoke as soon as the installer starts, in particular before probing for block and network devices. The autoinstall configuration is available at :file:`/autoinstall.yaml` (irrespective of how it was provided), and the file is re-read after the ``early-commands`` have run to allow them to alter the configuration if necessary. .. _ai-locale: locale ------- +~~~~~~ * **type:** string * **default:** ``en_US.UTF-8`` @@ -103,19 +87,18 @@ The locale to configure for the installed system. .. _ai-refresh-installer: refresh-installer ------------------ +~~~~~~~~~~~~~~~~~ * **type:** mapping * **default:** see below * **can be interactive:** true -Controls whether the installer updates to a new version available in the given -channel before continuing. +Controls whether the installer updates to a new version available in the given channel before continuing. The mapping contains keys: update -~~~~~~ +^^^^^^ * **type:** boolean * **default:** ``false`` @@ -123,7 +106,7 @@ update Whether to update or not. channel -~~~~~~~ +^^^^^^^ * **type:** string * **default:** ``"stable/ubuntu-$REL"`` @@ -133,24 +116,18 @@ The channel to check for updates. .. _ai-keyboard: keyboard --------- +~~~~~~~~ * **type:** mapping, see below * **default:** US English keyboard * **can be interactive:** true -The layout of any attached keyboard. Often systems being automatically -installed will not have a keyboard at all in which case the value used here -does not matter. - -The mapping keys correspond to settings in the :file:`/etc/default/keyboard` -configuration file. See the :manualpage:`keyboard(5) manual page ` -for more details. +The layout of any attached keyboard. The mapping keys correspond to settings in the :file:`/etc/default/keyboard` configuration file. See the :manualpage:`keyboard(5) manual page ` for more details. The mapping contains keys: layout -~~~~~~ +^^^^^^ * **type:** string * **default:** ``"us"`` @@ -158,7 +135,7 @@ layout Corresponds to the ``XKBLAYOUT`` setting. variant -~~~~~~~ +^^^^^^^ * **type:** string * **default:** ``""`` @@ -166,46 +143,53 @@ variant Corresponds to the ``XKBVARIANT`` setting. toggle -~~~~~~ +^^^^^^ * **type:** string or null * **default:** ``null`` -Corresponds to the value of ``grp:`` option from the ``XKBOPTIONS`` setting. -Acceptable values are (but note that the installer does not validate these): -``caps_toggle``, ``toggle``, ``rctrl_toggle``, ``rshift_toggle``, -``rwin_toggle``, ``menu_toggle``, ``alt_shift_toggle``, ``ctrl_shift_toggle``, -``ctrl_alt_toggle``, ``alt_caps_toggle``, ``lctrl_lshift_toggle``, -``lalt_toggle``, ``lctrl_toggle``, ``lshift_toggle``, ``lwin_toggle``, -``sclk_toggle`` - -The version of Subiquity released with 20.04 GA does not accept ``null`` for -this field due to a bug. +Corresponds to the value of ``grp:`` option from the ``XKBOPTIONS`` setting. Acceptable values are (the installer does not validate these): + +* ``caps_toggle`` +* ``toggle`` +* ``rctrl_toggle`` +* ``rshift_toggle`` +* ``rwin_toggle`` +* ``menu_toggle`` +* ``alt_shift_toggle`` +* ``ctrl_shift_toggle`` +* ``ctrl_alt_toggle`` +* ``alt_caps_toggle`` +* ``lctrl_lshift_toggle`` +* ``lalt_toggle`` +* ``lctrl_toggle`` +* ``lshift_toggle`` +* ``lwin_toggle`` +* ``sclk_toggle`` + +.. warning:: The version of Subiquity released with 20.04 GA does not accept ``null`` for this field due to a bug. .. _ai-source: source ------- +~~~~~~ * **type:** mapping, see below * **default:** see below * **can be interactive:** true search_drivers -~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^ * **type:** boolean * **default:** ``true`` (mostly, see below) -Whether the installer should search for available third-party drivers. When -set to ``false``, it disables the drivers :ref:`screen and section`. +Whether the installer searches for available third-party drivers. When set to ``false``, it disables the drivers :ref:`screen and section`. -The default is true for most installs but false when a "core boot" or -"enhanced secure boot" method is selected (where third-party drivers -cannot currently be installed). +The default is ``true`` for most installations, and ``false`` when a "core boot" or "enhanced secure boot" method is selected (where third-party drivers cannot be currently installed). id -~~ +^^ * **type:** string * **default:** identifier of the first available source. @@ -215,17 +199,13 @@ Identifier of the source to install (e.g., ``ubuntu-server-minimal``). .. _ai-network: network -------- +~~~~~~~ * **type:** Netplan-format mapping, see below * **default:** DHCP on interfaces named ``eth*`` or ``en*`` * **can be interactive:** true -`Netplan-formatted `_ network configuration. -This will be applied during installation as well as in the installed system. -The default is to interpret the configuration for the installation media, which runs -DHCP version 4 on any interface with a name matching ``eth*`` or ``en*`` but then -disables any interface that does not receive an address. +`Netplan-formatted `_ network configuration. This is applied during installation as well as in the installed system. The default is to interpret the configuration for the installation media, which runs DHCP version 4 on any interface with a name matching ``eth*`` or ``en*`` but then disables any interface that does not receive an address. For example, to run DHCP version 6 on a specific network interface: @@ -237,8 +217,7 @@ For example, to run DHCP version 6 on a specific network interface: enp0s31f6: dhcp6: true -Note that in the 20.04 GA release of Subiquity, the behaviour is slightly -different and requires you to write this with an extra ``network:`` key: +Note that in the 20.04 GA release of Subiquity, the behaviour is slightly different and requires you to write this with an extra ``network:`` key: .. code-block:: yaml @@ -249,48 +228,37 @@ different and requires you to write this with an extra ``network:`` key: enp0s31f6: dhcp6: true -Later versions support this syntax too (for compatibility) but if you can -assume a newer version you should use the former. +Versions later than 20.04 support this syntax, too (for compatibility). When using a newer version, use the regular syntax. .. _ai-proxy: proxy ------ +~~~~~ * **type:** URL or ``null`` * **default:** no proxy * **can be interactive:** true -The proxy to configure both during installation and for ``apt`` and for -``snapd`` in the target system. +The proxy to configure both during installation and for ``apt`` and ``snapd`` in the target system. .. _ai-apt: apt ---- +~~~ * **type:** mapping * **default:** see below * **can be interactive:** true -APT configuration, used both during the installation and once booted into the target -system. +APT configuration, used both during the installation and once booted into the target system. -This section historically used the same format as curtin, -`which is documented here `_. -Nonetheless, some key differences with the format supported by curtin have been introduced: +This section historically used the same format as curtin, which is documented in the `APT Source `_ section of the curtin documentation. Nonetheless, some key differences with the format supported by curtin have been introduced: -- Subiquity supports an alternative format for the ``primary`` section, - allowing configuration of a list of candidate primary mirrors. During - installation, Subiquity will automatically test the specified mirrors and - select the first one that seems usable. This new behaviour is only activated - when the ``primary`` section is wrapped in the ``mirror-selection`` section. +- Subiquity supports an alternative format for the ``primary`` section, allowing configuration of a list of candidate primary mirrors. During installation, Subiquity automatically tests the specified mirrors and selects the first one that appears usable. This new behaviour is only activated when the ``primary`` section is wrapped in the ``mirror-selection`` section. -- The ``fallback`` key controls what Subiquity should do if no primary mirror - is usable. +- The ``fallback`` key controls what Subiquity does when no primary mirror is usable. -- The ``geoip`` key controls whether a geoip lookup is done to determine the - correct country mirror. +- The ``geoip`` key controls whether to perform IP-based geolocation to determine the correct country mirror. The default is: @@ -308,59 +276,47 @@ The default is: fallback: abort geoip: true - mirror-selection -~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^ -if the ``primary`` section is contained within the ``mirror-selection`` -section, the automatic mirror selection is enabled. This is the default in new installations. +If the ``primary`` section is contained within the ``mirror-selection`` section, the automatic mirror selection is enabled. This is the default in new installations. -primary (when placed inside the ``mirror-selection`` section): -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +primary (when placed inside the ``mirror-selection`` section) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * **type:** custom, see below -In the new format, the ``primary`` section expects a list of mirrors, which -can be expressed in two different ways: +In the new format, the ``primary`` section expects a list of mirrors, which can be expressed in two different ways: -* The special value ``country-mirror`` +* The special ``country-mirror`` value * A mapping with the following keys: - * ``uri``: The URI of the mirror to use, e.g., ``http://fr.archive.ubuntu.com/ubuntu`` - * ``arches``: An optional list of architectures supported by the mirror. By - default, this list contains the current CPU architecture. + * ``uri``: The URI of the mirror to use, e.g., ``http://fr.archive.ubuntu.com/ubuntu``. + * ``arches``: An optional list of architectures supported by the mirror. By default, this list contains the current CPU architecture. fallback -~~~~~~~~ +^^^^^^^^ * **type:** string (enumeration) * **default:** abort -Controls what Subiquity should do if no primary mirror is usable. Supported -values are: +Controls what Subiquity does when no primary mirror is usable. Supported values are: -* ``abort`` -> abort the installation -* ``offline-install`` -> revert to an offline installation -* ``continue-anyway`` -> attempt to install the system anyway (not recommended, - the installation will certainly fail) +* ``abort``: abort the installation +* ``offline-install``: revert to an offline installation +* ``continue-anyway``: attempt to install the system anyway (not recommended; the installation fails) geoip -~~~~~ +^^^^^ * **type:** boolean * **default:** ``true`` -If geoip is true and one of the candidate primary mirrors has the special -value ``country-mirror``, a request is made to ``https://geoip.ubuntu.com/lookup``. -Subiquity then sets the mirror URI to ``http://CC.archive.ubuntu.com/ubuntu`` -(or similar for ports) where ``CC`` is the country code returned by the lookup. -If this section is not interactive, the request is timed out after 10 seconds. +If ``geoip`` is set to ``true`` and one of the candidate primary mirrors has the special value ``country-mirror``, a request is made to ``https://geoip.ubuntu.com/lookup``. Subiquity then sets the mirror URI to ``http://CC.archive.ubuntu.com/ubuntu`` (or similar for ports) where ``CC`` is the country code returned by the lookup. If this section is not interactive, the request expires after 10 seconds. -If the legacy behaviour (i.e., without mirror-selection) is in use, the geoip -request is made if the mirror to be used is the default, and its URI ends up -getting replaced by the proper country mirror URI. +If the legacy behaviour (i.e., without mirror-selection) is in use, the geolocation request is made if the mirror to be used is the default, and its URI is replaced by the proper country mirror URI. -If you just want to specify a mirror, you can use a configuration like this: +To specify a mirror, use a configuration like this: .. code-block:: yaml @@ -383,19 +339,16 @@ To add a PPA: .. _ai-storage: storage -------- +~~~~~~~ * **type:** mapping, see below -* **default:** use the ``lvm`` layout on single-disk systems; there is no default for - multiple-disk systems +* **default:** use the ``lvm`` layout on single-disk systems; there is no default for multiple-disk systems * **can be interactive:** true -Storage configuration is a complex topic and the description of the desired -configuration in the autoinstall file can also be complex. The installer -supports "layouts"; simple ways of expressing common configurations. +Storage configuration is a complex topic, and the description of the desired configuration in the autoinstall file can also be complex. The installer supports "layouts"; simple ways of expressing common configurations. Supported layouts -~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^ The three supported layouts at the time of writing are ``lvm``, ``direct`` and ``zfs``. @@ -412,8 +365,7 @@ The three supported layouts at the time of writing are ``lvm``, ``direct`` and ` name: zfs -By default these will install to the largest disk in a system, but you can -supply a match spec (see below) to indicate which disk to use: +By default, these layouts install to the largest disk in a system, but you can supply a match spec (see below) to indicate which disk to use: .. code-block:: yaml @@ -428,11 +380,9 @@ supply a match spec (see below) to indicate which disk to use: match: ssd: true -.. note:: - Match spec -- using "``match: {}``" will match an arbitrary disk +.. note:: Match spec -- using ``match: {}`` matches an arbitrary disk. -When using the ``lvm`` layout, LUKS encryption can be enabled by supplying a -password. +When using the ``lvm`` layout, LUKS encryption can be enabled by supplying a password. .. code-block:: yaml @@ -441,30 +391,26 @@ password. name: lvm password: LUKS_PASSPHRASE - The default is to use the ``lvm`` layout. Sizing-policy -~~~~~~~~~~~~~ +^^^^^^^^^^^^^ -The ``lvm`` layout, by default, attempts to leave room for snapshots and -further expansion. A sizing-policy key may be supplied to control this -behaviour. +The ``lvm`` layout, by default, attempts to leave room for snapshots and further expansion. A sizing-policy key may be supplied to control this behaviour. * **type:** string (enumeration) * **default:** scaled Supported values are: -* ``scaled`` -> adjust space allocated to the root LV based on space available - to the VG -* ``all`` -> allocate all remaining VG space to the root LV +* ``scaled``: Adjust space allocated to the root logical volume (LV) based on space available to the volume group (VG). +* ``all``: Allocate all remaining VG space to the root LV. -The scaling system is currently as follows: +The scaling system uses the following rules: -* Less than 10 GiB: use all remaining space for root file system +* Less than 10 GiB: use all remaining space for the root file system * Between 10--20 GiB: 10 GiB root file system -* Between 20--200 GiB: use half of remaining space for root file system +* Between 20--200 GiB: use half of the remaining space for the root file system * Greater than 200 GiB: 100 GiB root file system Example with no size scaling and a passphrase: @@ -478,19 +424,16 @@ Example with no size scaling and a passphrase: password: LUKS_PASSPHRASE Action-based configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For full flexibility, the installer allows storage configuration to be done using a syntax that is a superset of that supported by curtin, as described in the `Storage `_ section of the curtin documentation. -For full flexibility, the installer allows storage configuration to be done -using a syntax which is a superset of that supported by curtin, as described in -`the curtin documentation `_. +If the ``layout`` feature is used to configure the disks, the ``config`` section is not used. -If the ``layout`` feature is used to configure the disks, the ``config`` section -is not used. +The list of actions can be added under the ``config`` key, and the `grub `_ and `swap `_ +curtin configuration items can also be included here. -As well as putting the list of actions under the ``config`` key, the -`grub `_ and -`swap `_ -curtin configuration items can be put here. So a storage section might look like: +An example storage section: .. code-block:: yaml @@ -504,49 +447,34 @@ curtin configuration items can be put here. So a storage section might look like - type: partition ... - -The extensions to the curtin syntax are around disk selection and -partition/logical volume sizing. +The extensions to the curtin syntax allow for disk selection and partition or logical-volume sizing. Disk selection extensions -~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^ -Curtin supported identifying disks by serial (e.g. -``Crucial_CT512MX100SSD1_14250C57FECE``) or by path (e.g. ``/dev/sdc``) and the -server installer supports this as well. The installer additionally supports a -''match spec'' on a disk action that supports more flexible matching. +Curtin supported identifying disks by serial numbers (e.g. ``Crucial_CT512MX100SSD1_14250C57FECE``) or by path (e.g. ``/dev/sdc``), and the server installer supports this, too. The installer additionally supports a "match spec" on a disk action, which provides for more flexible matching. -The actions in the storage configuration are processed in the order they are in the -autoinstall file. Any disk action is assigned a matching disk -- chosen -arbitrarily from the set of unassigned disks if there is more than one, and -causing the installation to fail if there is no unassigned matching disk. +The actions in the storage configuration are processed in the order they are in the autoinstall file. Any disk action is assigned a matching disk -- chosen arbitrarily from the set of unassigned disks if there is more than one, and causing the installation to fail if there is no unassigned matching disk. A match spec supports the following keys: -* ``model: foo``: matches a disk where ``ID_VENDOR=foo`` in udev, supporting - globbing -* ``path: foo``: matches a disk based on path (e.g. ``/dev/sdc``), supporting - globbing (the globbing support distinguishes this from specifying path: foo - directly in the disk action) -* ``id_path: foo``: matches a disk where ``ID_PATH=foo`` in udev, supporting - globbing -* ``devpath: foo``: matches a disk where ``DEVPATH=foo`` in udev, supporting - globbing -* ``serial: foo``: matches a disk where ``ID_SERIAL=foo`` in udev, supporting - globbing (the globbing support distinguishes this from specifying serial: foo - directly in the disk action) -* ``ssd: true|false``: matches a disk that is or is not an SSD (vs. a rotating - drive) -* ``size: largest|smallest``: take the largest or smallest disk rather than an - arbitrary one if there are multiple matches (support for ``smallest`` added - in version 20.06.1) - -A special sort of key is ``install-media: true``, which will take the disk the -installer was loaded from (the ``ssd`` and ``size`` selectors will never return -this disk). If installing to the installation media, care obviously needs to be taken -to not overwrite the installer itself! - -So for example, to match an arbitrary disk it is simply: +* ``model: value``: matches a disk where ``ID_VENDOR=value`` in udev, supporting globbing + +* ``path: value``: matches a disk based on path (e.g. ``/dev/sdc``), supporting globbing (the globbing support distinguishes this from specifying ``path: value`` directly in the disk action) + +* ``id_path: value``: matches a disk where ``ID_PATH=value`` in udev, supporting globbing + +* ``devpath: value``: matches a disk where ``DEVPATH=value`` in udev, supporting globbing + +* ``serial: value``: matches a disk where ``ID_SERIAL=value`` in udev, supporting globbing (the globbing support distinguishes this from specifying ``serial: value`` directly in the disk action) + +* ``ssd: true|false``: matches a disk that is or is not an SSD (as opposed to a rotating drive) + +* ``size: largest|smallest``: take the largest or smallest disk rather than an arbitrary one if there are multiple matches (support for ``smallest`` added in version 20.06.1) + +A special sort of key is ``install-media: true``, which takes the disk the installer was loaded from (the ``ssd`` and ``size`` selectors never return this disk). If installing to the installation media, be careful to not overwrite the installer itself. + +For example, to match an arbitrary disk: .. code-block:: yaml @@ -572,20 +500,16 @@ To match a Seagate drive: match: model: Seagate - Partition/logical volume extensions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The size of a partition or logical volume in curtin is specified as a number of bytes. The autoinstall configuration is more flexible: + +* You can specify the size using the ``1G``, ``512M`` syntax supported in the installer UI. -The size of a partition or logical volume in curtin is specified as a number of -bytes. The autoinstall configuration is more flexible: +* You can specify the size as a percentage of the containing disk (or RAID), e.g. ``50%``. -* You can specify the size using the "1G", "512M" syntax supported in the - installer UI. -* You can specify the size as a percentage of the containing disk (or RAID), - e.g. "50%". -* For the last partition specified for a particular device, you can specify - the size as "-1" to indicate that the partition should fill the remaining - space. +* For the last partition specified for a particular device, you can specify the size as ``-1`` to indicate that the partition should fill the remaining space. .. code-block:: yaml @@ -604,45 +528,39 @@ bytes. The autoinstall configuration is more flexible: .. _ai-identity: identity --------- +~~~~~~~~ * **type:** mapping, see below * **default:** no default * **can be interactive:** true -Configure the initial user for the system. This is the only configuration key that -must be present (unless the :ref:`user-data section ` is present, -in which case it is optional). +Configure the initial user for the system. This is the only configuration key that must be present (unless the :ref:`user-data section ` is present, in which case it is optional). A mapping that can contain keys, all of which take string values: realname -~~~~~~~~ +^^^^^^^^ The real name for the user. This field is optional. username -~~~~~~~~ +^^^^^^^^ The user name to create. hostname -~~~~~~~~ +^^^^^^^^ The hostname for the system. password -~~~~~~~~ +^^^^^^^^ -The password for the new user, encrypted. This is required for use with -``sudo``, even if SSH access is configured. +The password for the new user, encrypted. This is required for use with ``sudo``, even if SSH access is configured. -The encrypted password string must conform to what the -``passwd`` command requires. See the :manualpage:`passwd(1) manual page ` -for details. Quote the password hash to ensure correct treatment of any special characters. +The encrypted password string must conform to what the ``passwd`` command requires. See the :manualpage:`passwd(1) manual page ` for details. Quote the password hash to ensure correct treatment of any special characters. -Several tools can generate the encrypted password, such as ``mkpasswd`` from the -``whois`` package, or ``openssl passwd``. +Several tools can generate the encrypted password, such as ``mkpasswd`` from the ``whois`` package, or ``openssl passwd``. Example: @@ -657,7 +575,7 @@ Example: .. _ai-active-directory: active-directory ----------------- +~~~~~~~~~~~~~~~~ * **type:** mapping, see below * **default:** no default @@ -668,27 +586,26 @@ Accepts data required to join the target system in an Active Directory domain. A mapping that can contain keys, all of which take string values: admin-name -~~~~~~~~~~ +^^^^^^^^^^ -A domain account name with privilege to perform the join operation. That -account's password will be requested during run time. +A domain account name with the privilege to perform the join operation. The account password is requested during run time. domain-name -~~~~~~~~~~~ +^^^^^^^^^^^ The Active Directory domain to join. .. _ai-ubuntu-pro: ubuntu-pro ----------- +~~~~~~~~~~ * **type:** mapping, see below * **default:** see below * **can be interactive:** true token -~~~~~ +^^^^^ * **type:** string * **default:** no token @@ -698,32 +615,32 @@ A contract token to attach to an existing Ubuntu Pro subscription. .. _ai-ssh: ssh ---- +~~~ * **type:** mapping, see below * **default:** see below * **can be interactive:** true -Configure SSH for the installed system. A mapping that can contain keys: +Configure SSH for the installed system. A mapping that can contain the following keys: install-server -~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^ * **type:** boolean * **default:** ``false`` -Whether to install OpenSSH server in the target system. +Whether to install the OpenSSH server in the target system. -:spellexception:`authorized-keys` -~~~~~~~~~~~~~~~ +authorized-keys +^^^^^^^^^^^^^^^ * **type:** list of strings * **default:** ``[]`` -A list of SSH public keys to install in the initial user's account. +A list of SSH public keys to install in the initial user account. allow-pw -~~~~~~~~ +^^^^^^^^ * **type:** boolean * **default:** ``true`` if ``authorized_keys`` is empty, ``false`` otherwise @@ -731,14 +648,13 @@ allow-pw .. _ai-codecs: codecs ------- +~~~~~~ * **type:** mapping, see below * **default:** see below * **can be interactive:** no -Configure whether common restricted packages (including codecs) from -[multiverse] should be installed. +Configure whether common restricted packages (including codecs) from the multiverse repository are to be installed. install ~~~~~~~ @@ -746,19 +662,19 @@ install * **type:** boolean * **default:** ``false`` -Whether to install the ubuntu-restricted-addons package. +Whether to install the ``ubuntu-restricted-addons`` package. .. _ai-drivers: drivers -------- +~~~~~~~ * **type:** mapping, see below * **default:** see below * **can be interactive:** true install -~~~~~~~ +^^^^^^^ * **type:** boolean * **default:** ``false`` @@ -768,36 +684,32 @@ Whether to install the available third-party drivers. .. _ai-oem: oem ---- +~~~ * **type:** mapping, see below * **default:** see below * **can be interactive:** no install -~~~~~~~ +^^^^^^^ * **type:** boolean or string (special value ``auto``) * **default:**: ``auto`` -Whether to install the available OEM meta-packages. The special value ``auto`` --- which is the default -- enables the installation on ubuntu-desktop but not -on ubuntu-server. This option has no effect on core boot classic. +Whether to install the available OEM meta-packages. The special value ``auto`` -- which is the default -- enables the installation on Ubuntu Desktop but not on Ubuntu Server. This option has no effect on core boot classic. .. _ai-snaps: snaps ------ +~~~~~ * **type:** list * **default:** install no extra snaps * **can be interactive:** true -A list of snaps to install. Each snap is represented as a mapping with required -``name`` and optional ``channel`` (defaulting to ``stable``) and classic -(defaulting to ``false``) keys. For example: +A list of snaps to install. Each snap is represented as a mapping with a required ``name`` and an optional ``channel`` (default is ``stable``) and classic (default is ``false``) keys. For example: -.. code-block: yaml +.. code-block:: yaml snaps: - name: etcd @@ -807,50 +719,45 @@ A list of snaps to install. Each snap is represented as a mapping with required .. _ai-debconf-selections: debconf-selections ------------------- +~~~~~~~~~~~~~~~~~~ * **type:** string * **default:** no configuration * **can be interactive:** no -The installer will update the target with debconf set-selection values. Users -will need to be familiar with the package debconf options. +The installer updates the target with debconf ``set-selection`` values. Users need to be familiar with the options of the ``debconf`` package. .. _ai-packages: packages --------- +~~~~~~~~ * **type:** list * **default:** no packages * **can be interactive:** no -A list of packages to install into the target system. More precisely, a list of -strings to pass to "``apt-get install``", so this includes things like task -selection (``dns-server^``) and installing particular versions of a package -(``my-package=1-1``). +A list of packages to install into the target system. Specifically, a list of strings to pass to the :command:`apt-get install` command. Therefore, this includes things such as task selection (``dns-server^``) and installing particular versions of a package (``my-package=1-1``). .. _ai-kernel: kernel ------- +~~~~~~ * **type:** mapping (mutually exclusive), see below * **default:** default kernel * **can be interactive:** no -Which kernel gets installed. Either the name of the package or the name of the -flavour must be specified. +Which kernel gets installed. Either the name of the package or the name of the flavour must be specified. package -~~~~~~~ +^^^^^^^ **type:** string -The name of the package, e.g., ``linux-image-5.13.0-40-generic`` +The name of the package, e.g., ``linux-image-5.13.0-40-generic``. flavor -~~~~~~ +^^^^^^ * **type:** string @@ -859,41 +766,38 @@ The ``flavor`` of the kernel, e.g., ``generic`` or ``hwe``. .. _ai-timezone: timezone --------- +~~~~~~~~ * **type:** string * **default:** no timezone * **can be interactive:** no -The timezone to configure on the system. The special value "geoip" can be used -to query the timezone automatically over the network. +The timezone to configure on the system. The special value ``geoip`` can be used to query the timezone automatically over the network. .. _ai-updates: updates -------- +~~~~~~~ * **type:** string (enumeration) * **default:** ``security`` * **can be interactive:** no -The type of updates that will be downloaded and installed after the system -installation. Supported values are: +The type of updates that will be downloaded and installed after the system installation. Supported values are: -* ``security`` -> download and install updates from the -security pocket -* ``all`` -> also download and install updates from the -updates pocket +* ``security``: download and install updates from the ``-security`` pocket. +* ``all``: also download and install updates from the ``-updates`` pocket. .. _ai-shutdown: shutdown --------- +~~~~~~~~ * **type:** string (enumeration) * **default:** ``reboot`` * **can be interactive:** no -Request the system to power off or reboot automatically after the installation -has finished. Supported values are: +Request the system to power off or reboot automatically after the installation has finished. Supported values are: * ``reboot`` * ``poweroff`` @@ -901,65 +805,47 @@ has finished. Supported values are: .. _ai-late-commands: late-commands -------------- +~~~~~~~~~~~~~ * **type:** :ref:`command list` * **default:** no commands * **can be interactive:** no -Shell commands to run after the installation has completed successfully and any -updates and packages installed, just before the system reboots. They are run in -the installer environment with the installed system mounted at ``/target``. You -can run ``curtin in-target -- $shell_command`` (with the version of Subiquity -released with 20.04 GA you need to specify this as -``curtin in-target --target=/target -- $shell_command``) to run in the target -system (similar to how plain ``in-target`` can be used in -``d-i preseed/late_command``). +Shell commands to run after the installation has completed successfully and any updates and packages installed, just before the system reboots. The commands are run in the installer environment with the installed system mounted at ``/target``. You can run ``curtin in-target -- $shell_command`` (with the version of Subiquity +released with 20.04 GA, you need to specify this as ``curtin in-target --target=/target -- $shell_command``) to run in the target system (similar to how plain ``in-target`` can be used in ``d-i preseed/late_command``). .. _ai-error-commands: error-commands --------------- +~~~~~~~~~~~~~~ * **type:** :ref:`command list` * **default:** no commands * **can be interactive:** no -Shell commands to run after the installation has failed. They are run in the -installer environment, and the target system (or as much of it as the installer -managed to configure) will be mounted at ``/target``. Logs will be available -at :file:`/var/log/installer` in the live session. +Shell commands to run after the installation has failed. They are run in the installer environment, and the target system (or as much of it as the installer managed to configure) is mounted at ``/target``. Logs will be available in :file:`/var/log/installer` in the live session. .. _ai-reporting: reporting ---------- +~~~~~~~~~ * **type:** mapping -* **default:** ``type: print`` which causes output on tty1 and any configured - serial consoles +* **default:** ``type: print`` (which causes output on ``tty1`` and any configured serial consoles) * **can be interactive:** no -The installer supports reporting progress to a variety of destinations. Note -that this section is ignored if there are any :ref:`interactive sections `; it only applies to fully automated installs. +The installer supports reporting progress to a variety of destinations. Note that this section is ignored if there are any :ref:`interactive sections `; it only applies to fully automated installations. -The configuration, and indeed the implementation, is 90% the same as -`that used by curtin `_. +The configuration is similar to that used by curtin. See the `Reporting `_ section of the curtin documentation. -Each key in the ``reporting`` mapping in the configuration defines a destination, -where the ``type`` sub-key is one of: +Each key in the ``reporting`` mapping in the configuration defines a destination where the ``type`` sub-key is one of: -**The rsyslog reporter does not yet exist** +* ``print``: print progress information on ``tty1`` and any configured serial console. There is no other configuration. +* ``rsyslog``: report progress via rsyslog. The ``destination`` key specifies where to send output. (The rsyslog reporter does not yet exist.) +* ``webhook``: report progress by sending JSON reports to a URL using POST requests. Accepts the same `configuration as curtin `_. +* ``none``: do not report progress. Only useful to inhibit the default output. -* **print**: print progress information on tty1 and any configured serial - console. There is no other configuration. -* **rsyslog**: report progress via rsyslog. The **destination** key specifies - where to send output. -* **webhook**: report progress by sending JSON reports to a URL using POST requests. Accepts the - same `configuration as curtin `_. -* **none**: do not report progress. Only useful to inhibit the default output. - -Examples: +Reporting examples: The default configuration is: @@ -995,23 +881,19 @@ Report to a curtin-style webhook: hook: type: webhook endpoint: http://example.com/endpoint/path - consumer_key: "ck_foo" - consumer_secret: "cs_foo" - token_key: "tk_foo" + consumer_key: "ck_value" + consumer_secret: "cs_value" + token_key: "tk_value" token_secret: "tk_secret" level: INFO - .. _ai-user-data: user-data ---------- +~~~~~~~~~ * **type:** mapping * **default:** ``{}`` * **can be interactive:** no -Provide cloud-init user data which will be merged with the user data the -installer produces. If you supply this, you don't need to supply an -:ref:`identity section ` (but then it's your responsibility to -make sure that you can log into the installed system!). +Provide cloud-init user data, which will be merged with the user data the installer produces. If you supply this, you don't need to supply an :ref:`identity section ` (in that case, ensure you can log in to the installed system). diff --git a/doc/reference/autoinstall-schema.rst b/doc/reference/autoinstall-schema.rst index 63a6f6ae1..c655b871e 100644 --- a/doc/reference/autoinstall-schema.rst +++ b/doc/reference/autoinstall-schema.rst @@ -1,35 +1,31 @@ .. _autoinstall_schema: Autoinstall schema -****************** +================== -The server installer validates the provided autoinstall configuration against a -:ref:`JSON schema`. +The server installer validates the provided autoinstall configuration against a :ref:`JSON schema`. How the configuration is validated -================================== +---------------------------------- -Although the schema is presented below as a single document, and if you want -to pre-validate your configuration you should validate it against this document, the -configuration is not actually validated against this document at run time. What -happens instead is that some sections are loaded, validated, and applied -first, before all other sections are validated. In detail: +This reference manual presents the schema as a single document. Use it pre-validate your configuration. + +At run time, the configuration is not validated against this document. Instead, configuration sections are loaded and validated in this order: 1. The reporting section is loaded, validated and applied. 2. The error commands are loaded and validated. 3. The early commands are loaded and validated. 4. The early commands, if any, are run. -5. The configuration is reloaded, and now all sections are loaded and validated. +5. The configuration is reloaded, and all sections are loaded and validated. -This is so that validation errors in most sections can be reported via the -reporting and error-commands configuration, as all other errors are. +This is to ensure that potential validation errors in most sections can be reported using the reporting and error-commands configuration the same way as other errors. .. _autoinstall_JSON_schema: Schema -====== +------ -The `JSON schema`_ for autoinstall data is as follows: +The `JSON schema`_ for autoinstall data: .. code-block:: JSON @@ -579,11 +575,11 @@ The `JSON schema`_ for autoinstall data is as follows: } Regeneration -============ +------------ -The schema above can be regenerated by running ``make schema`` in a Subiquity -source checkout. +To regenerate the schema, run ``make schema`` in the root directory of the `Subiquity source repository`_. .. LINKS .. _JSON schema: https://json-schema.org/ +.. _Subiquity source repository: https://github.com/canonical/subiquity diff --git a/doc/reference/index.rst b/doc/reference/index.rst index fc2a0d872..c01102a23 100644 --- a/doc/reference/index.rst +++ b/doc/reference/index.rst @@ -1,14 +1,12 @@ Reference -********* +========= -Our reference section contains support information for Subiquity. -This includes details on the network requirements, API definitions, support -matrices and so on. +The reference section contains support information for Subiquity. This includes details on the network requirements, API definitions, support matrices, and other. ----- Autoinstall reference manual -============================ +---------------------------- .. toctree:: :maxdepth: 1 diff --git a/doc/reuse/substitutions.txt b/doc/reuse/substitutions.txt index 55a629f26..5d9ee6a5b 100644 --- a/doc/reuse/substitutions.txt +++ b/doc/reuse/substitutions.txt @@ -1,3 +1,3 @@ -.. |ubuntu-latest-version| replace:: 23.04 -.. |ubuntu-latest-codename| replace:: Lunar Lobster +.. |ubuntu-latest-version| replace:: 23.10 +.. |ubuntu-latest-codename| replace:: Mantic Minotaur .. role:: command(literal)