ConfigReference
Size: 10777
Comment:
|
Size: 16117
Comment:
|
Deletions are marked like this. | Additions are marked like this. |
Line 1: | Line 1: |
||<#FF5555> '''This document is entirely a description of something that does not yet exist''' || |
|
Line 5: | Line 3: |
||<#FF5555> '''This document is entirely a description of something that does not yet exist''' || |
|
Line 15: | Line 11: |
A schema for the config file should be written down at some point. | Autoinstall configs [[FoundationsTeam/AutomatedServerInstalls/ConfigSchema|are validated against a JSON schema]] before they are used. <<Anchor(commandlist)>> = Command lists = Several config 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 install (except for error-commands, where it is ignored). |
Line 46: | Line 47: |
You can use the special section name of "*" to indicate that the installer should ask all the usual questions -- in this case, the autoinstall.yaml file does 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 `autoinstall.yaml` file is not really an "autoinstall" file at all, instead just a way to change the defaults in the UI. |
Line 50: | Line 51: |
== early_commands == '''type:''' list |
If there are any interactive sections at all, the [[#reporting|reporting]] key is ignored. == early-commands == '''type:''' [[#commandlist|command list]] |
Line 58: | Line 61: |
A list of shell commands to invoke as soon as the installer starts, in particular before probing for block and network devices. The autoinstall config is available at /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 config 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 config is available at `/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 config if necessary. |
Line 65: | Line 67: |
'''default:''' en_US.UTF-8 <<BR>> '''can be interactive:''' yes The locale to configure for the installer. |
'''default:''' `en_US.UTF-8` <<BR>> '''can be interactive:''' yes, always interactive if any section is The locale to configure for the installed system. == refresh-installer == '''type:''' mapping <<BR>> '''default:''' see below <<BR>> '''can be interactive:''' yes Controls whether the installer updates to a new version available in the given channel before continuing. The mapping contains keys: === update === '''type:''' boolean <<BR>> '''default''': `no` Whether to update or not. === channel === '''type:''' string <<BR>> '''default''': `"stable/ubuntu-$REL"` The channel to check for updates. |
Line 81: | Line 111: |
The mapping's keys correspond to settings in the `/etc/default/keyboard` configuration file. See [[http://manpages.ubuntu.com/manpages/bionic/en/man5/keyboard.5.html|its manual page]] for more details. The mapping contains keys: === layout === '''type:''' string <<BR>> '''default''': `"us"` Corresponds to the `XKBLAYOUT` setting. === variant === '''type:''' string <<BR>> '''default''': `""` Corresponds to the `XKBVARIANT` setting. === toggle === '''type:''' string or null <<BR>> '''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` |
|
Line 93: | Line 151: |
'''type:''' URL | '''type:''' URL or `null` |
Line 101: | Line 159: |
== mirror == '''type:''' URL <<BR>> '''default:''' http://archive.ubuntu.com/ubuntu or http://ports.ubuntu.com/ubuntu-ports depending on architecture <<BR>> '''can be interactive:''' yes The archive mirror to use. == filesystem == |
== apt == '''type:''' mapping <<BR>> '''default:''' see below <<BR>> '''can be interactive:''' yes Apt configuration, used both during the install and once booted into the target system. This uses the same format as curtin which is documented at https://curtin.readthedocs.io/en/latest/topics/apt_source.html, with one extension: the `geoip` key controls whether a geoip lookup is done. The default is: {{{ apt: preserve_sources_list: false primary: - arches: [i386, amd64] uri: "http://archive.ubuntu.com/ubuntu" - arches: [default] uri: "http://ports.ubuntu.com/ubuntu-ports" geoip: true }}} If geoip is true and the mirror to be used is the default, a request is made to `https://geoip.ubuntu.com/lookup` and the mirror uri to be used changed to be `http://CC.archive.ubuntu.com/ubuntu` where `CC` is the country code returned by the lookup (or similar for ports). If this section is not interactive, the request is timed out after 10 seconds. Any supplied config is merged with the default rather than replacing it. If you just want to set a mirror, use a config like this: {{{ apt: primary: - arches: [default] - uri: YOUR_MIRROR_GOES_HERE }}} To add a ppa: {{{ apt: sources: curtin-ppa: source: ppa:curtin-dev/test-archive }}} == storage == |
Line 119: | Line 214: |
Filesystem configuration is a complex topic and the description of the desired configuration in the autoinstall file can necessarily 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 necessarily also be complex. The installer supports "layouts", simple ways of expressing common configurations. |
Line 123: | Line 218: |
The two supported layouts at the time of writing are "lvm" and "disk". {{{ filesystem: |
The two supported layouts at the time of writing are "lvm" and "direct". {{{ storage: |
Line 129: | Line 224: |
filesystem: | storage: |
Line 131: | Line 226: |
name: disk }}} In a single disk system they will just install to that single disk but in a system with multiple disks you must supply a match spec (see below) to indicate which disk to use: {{{ filesystem: |
name: direct }}} 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: {{{ storage: |
Line 142: | Line 237: |
filesystem: | storage: |
Line 151: | Line 246: |
The default in a single disk system is to use the lvm layout. There is no default in a system with multiple disks. | The default is to use the lvm layout. |
Line 155: | Line 250: |
For full flexibility, the installer allows filesystem configuration to be done using a syntax which is a superset of that supported by curtin, described at https://curtin.readthedocs.io/en/latest/topics/storage.html. | For full flexibility, the installer allows storage configuration to be done using a syntax which is a superset of that supported by curtin, described at https://curtin.readthedocs.io/en/latest/topics/storage.html. As well as putting the list of actions under the 'config' key, the [[https://curtin.readthedocs.io/en/latest/topics/config.html#swap|swap]] and [[https://curtin.readthedocs.io/en/latest/topics/config.html#grub|grub]] curtin config items can be put here -- although curtin expects paths in install_devices and the server installer expects action ids. So a storage section might look like: {{{ storage: grub: install_devices: - disk0 swap: size: 0 config: - type: disk id: disk0 serial: ADATA_SX8200PNP_XXXXXXXXXXX - type: partition ... }}} |
Line 159: | Line 269: |
The actions in the filesystem config 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 config 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. |
Line 164: | Line 274: |
* `path: foo`: matches a disk where DEVPATH=foo in udev, supporting globbing (the globbing support distinguishes this from specifying path: foo directly in the disk action) | |
Line 194: | Line 305: |
||<#FF5555> '''The snap described here does not yet exist''' || |
|
Line 196: | Line 309: |
Another extension to curtin syntax is how the size of partitions or LVM logical volumes are specified. Curtin just takes a size for this, but the server installer allows sizes to be specified as percentages of the containing device, or using min/priority/max as in d-i: (XXX I don't actually understand how min/priority/max works in d-i). {{{ |
Another extension to curtin syntax is how the size of partitions or LVM logical volumes are specified. Curtin just takes a size for this, but the server installer allows sizes to be specified as percentages of the containing device. Also, a negative size can be used for the final partition to indicate that the partition should use all the remaining space. {{{ - type: partition id: boot-partition device: root-disk size: 10% - type: partition id: root-partition size: 20G |
Line 201: | Line 321: |
device: data-disk size: 75% - type: partition id: boot-partition device: boot-disk size: min: 512M priority: 600M max: 2G |
device: root-disk size: -1 |
Line 220: | Line 333: |
Configure the initial user for the system. This is the only config key that must be present (unless the user-data section is present, in which case it is optional). A mapping that can contain keys: |
Configure the initial user for the system. This is the only config key that must be present (unless the [[#user-data|user-data section]] is present, in which case it is optional). A mapping that can contain keys, all of which take string values: |
Line 225: | Line 338: |
The real name for the user. This field is optional. |
|
Line 226: | Line 342: |
The user name to create. |
|
Line 227: | Line 346: |
The hostname for the system. |
|
Line 229: | Line 351: |
The password for the new user, crypted. This is required for use with sudo, even if SSH access is configured. |
|
Line 233: | Line 357: |
'''default:''' `{install_server: no, authorized_keys: [], allow_pw: yes}` | '''default:''' see below |
Line 239: | Line 363: |
=== install_server === === authorized_keys === === allow_pw === |
=== install-server === '''type:''' boolean <<BR>> '''default:''' `false` Whether to install OpenSSH server in the target system. === authorized-keys === '''type:''' list of strings <<BR>> '''default:''' `[]` A list of SSH public keys to install in the initial user's account. === allow-pw === '''type:''' boolean <<BR>> '''default:''' `true` if `authorized_keys` is empty, `false` otherwise |
Line 251: | Line 393: |
Snaps to install, in the format "$snap_name/$channel". == debconf_selections == |
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: {{{ snaps: - name: etcd channel: edge classic: false }}} == debconf-selections == |
Line 271: | Line 420: |
A list of packages to install into the target system. == late_commands == '''type:''' list |
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`). == late-commands == '''type:''' [[#commandlist|command list]] |
Line 281: | Line 430: |
Shell commands to run after the install 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. == error_commands == '''type:''' list |
Shell commands to run after the install 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` to run in the target system (similar to how plain `in-target` can be used in `d-i preseed/late_command`). == error-commands == '''type:''' [[#commandlist|command list]] |
Line 301: | Line 450: |
The installer supports reporting progress to a variety of destinations. Note that this section is ignored if there are any 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 [[#interactive-sections|interactive sections]]; it only applies to fully automated installs. The config, and indeed the implementation, is 90% the same as [[https://curtin.readthedocs.io/en/latest/topics/reporting.html|that used by curtin]]. |
Line 305: | Line 456: |
||<#FF5555> '''The rsyslog reporter does not yet exist''' || |
|
Line 306: | Line 459: |
* '''rsyslog''': report progress via rsyslog. The '''destination''' key specifies where to send output. * '''webhook''': report progress via POSTing JSON reports to a URL. Accepts the same configuration as curtin's option, documented at https://curtin.readthedocs.io/en/latest/topics/reporting.html. |
* '''rsyslog''': report progress via rsyslog. The '''destination''' key specifies where to send output. * '''webhook''': report progress via POSTing JSON reports to a URL. Accepts the same configuration as [[https://curtin.readthedocs.io/en/latest/topics/reporting.html#webhook-reporter|curtin]]. |
Line 359: | Line 512: |
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 identity section. | 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 [[#identity|identity section]] (but then it's your responsibility to make sure that you can log into the installed system!). |
Automated Server Installs Config File Reference
Contents
Overall format
The autoinstall file is YAML. At top level it must be a mapping containing the keys described in this document. Unrecognized keys are ignored.
Schema
Autoinstall configs are validated against a JSON schema before they are used.
Command lists
Several config 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 install (except for error-commands, where it is ignored).
Top-level keys
version
type: integer
default: no default
A future-proofing config file version field. Currently this must be "1".
interactive-sections
type: list of strings
default: []
A list of config keys to still show in the UI. So for example:
version: 1 interactive-sections: - network identity: username: ubuntu password: $crypted_pass
Would stop on the network screen and allow 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 autoinstall.yaml file is not really an "autoinstall" file at all, instead just a way to change the defaults in the UI.
Not all config 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 reporting key is ignored.
early-commands
type: 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 config is available at /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 config if necessary.
locale
type: string
default: en_US.UTF-8
can be interactive: yes, always interactive if any section is
The locale to configure for the installed system.
refresh-installer
type: mapping
default: see below
can be interactive: yes
Controls whether the installer updates to a new version available in the given channel before continuing.
The mapping contains keys:
update
type: boolean
default: no
Whether to update or not.
channel
type: string
default: "stable/ubuntu-$REL"
The channel to check for updates.
keyboard
type: mapping, see below
default: US English keyboard
can be interactive: yes
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's keys correspond to settings in the /etc/default/keyboard configuration file. See its manual page for more details.
The mapping contains keys:
layout
type: string
default: "us"
Corresponds to the XKBLAYOUT setting.
variant
type: string
default: ""
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
network
type: netplan-format mapping, see below
default: DHCP on interfaces named eth* or en*
can be interactive: yes
netplan formatted network configuration. This will be applied during installation as well as in the installed system. The default is to interpret the config for the install media, which runs DHCPv4 on any interface with a name matching "eth*" or "en*" but then disables any interface that does not receive an address.
proxy
type: URL or null
default: no proxy
can be interactive: yes
The proxy to configure both during installation and for apt and for snapd in the target system.
apt
type: mapping
default: see below
can be interactive: yes
Apt configuration, used both during the install and once booted into the target system.
This uses the same format as curtin which is documented at https://curtin.readthedocs.io/en/latest/topics/apt_source.html, with one extension: the geoip key controls whether a geoip lookup is done.
The default is:
apt: preserve_sources_list: false primary: - arches: [i386, amd64] uri: "http://archive.ubuntu.com/ubuntu" - arches: [default] uri: "http://ports.ubuntu.com/ubuntu-ports" geoip: true
If geoip is true and the mirror to be used is the default, a request is made to https://geoip.ubuntu.com/lookup and the mirror uri to be used changed to be http://CC.archive.ubuntu.com/ubuntu where CC is the country code returned by the lookup (or similar for ports). If this section is not interactive, the request is timed out after 10 seconds.
Any supplied config is merged with the default rather than replacing it.
If you just want to set a mirror, use a config like this:
apt: primary: - arches: [default] - uri: YOUR_MIRROR_GOES_HERE
To add a ppa:
apt: sources: curtin-ppa: source: ppa:curtin-dev/test-archive
storage
type: mapping, see below
default: use "lvm" layout in a single disk system, no default in a multiple disk system
can be interactive: yes
Storage configuration is a complex topic and the description of the desired configuration in the autoinstall file can necessarily also be complex. The installer supports "layouts", simple ways of expressing common configurations.
Supported layouts
The two supported layouts at the time of writing are "lvm" and "direct".
storage: layout: name: lvm storage: layout: name: direct
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:
storage: layout: name: lvm match: serial: CT* storage: layout: name: disk match: ssd: yes
(you can just say "match: {}" to match an arbitrary disk)
The default is to use the lvm layout.
action-based config
For full flexibility, the installer allows storage configuration to be done using a syntax which is a superset of that supported by curtin, described at https://curtin.readthedocs.io/en/latest/topics/storage.html. As well as putting the list of actions under the 'config' key, the swap and grub curtin config items can be put here -- although curtin expects paths in install_devices and the server installer expects action ids. So a storage section might look like:
storage: grub: install_devices: - disk0 swap: size: 0 config: - type: disk id: disk0 serial: ADATA_SX8200PNP_XXXXXXXXXXX - type: partition ...
The extensions to the curtin syntax are mostly around disk selection. 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.
The actions in the storage config 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 where DEVPATH=foo in udev, supporting globbing (the globbing support distinguishes this from specifying path: foo directly in the disk action)
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: yes|no: matches a disk that is or is not an SSD (vs a rotating drive)
size: largest: take the largest disk rather than an arbitrary one if there are multiple matches
So for example, to match an arbitrary disk it is simply:
- type: disk id: disk0
To match the largest ssd:
- type: disk id: big-fast-disk match: ssd: yes size: largest
To match a Seagate drive:
- type: disk id: data-disk match: model: Seagate
The snap described here does not yet exist |
autoinstall-editor supports creating and editing configs with arbitrary disk match specs.
Another extension to curtin syntax is how the size of partitions or LVM logical volumes are specified. Curtin just takes a size for this, but the server installer allows sizes to be specified as percentages of the containing device. Also, a negative size can be used for the final partition to indicate that the partition should use all the remaining space.
- type: partition id: boot-partition device: root-disk size: 10% - type: partition id: root-partition size: 20G - type: partition id: data-partition device: root-disk size: -1
identity
type: mapping, see below
default: no default
can be interactive: yes
Configure the initial user for the system. This is the only config key that must be present (unless the 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, crypted. This is required for use with sudo, even if SSH access is configured.
ssh
type: mapping, see below
default: see below
can be interactive: yes
Configure ssh for the installed system. A mapping that can contain keys:
install-server
type: boolean
default: false
Whether to install OpenSSH server in the target system.
authorized-keys
type: list of strings
default: []
A list of SSH public keys to install in the initial user's account.
allow-pw
type: boolean
default: true if authorized_keys is empty, false otherwise
snaps
type: list
default: install no extra snaps
can be interactive: yes
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:
snaps: - name: etcd channel: edge classic: false
debconf-selections
type: string
default: no config
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.
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).
late-commands
type: command list
default: no commands
can be interactive: no
Shell commands to run after the install 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 to run in the target system (similar to how plain in-target can be used in d-i preseed/late_command).
error-commands
type: command list
default: no commands
can be interactive: no
Shell commands to run after the install 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 /var/log/installer in the live session.
reporting
type: mapping
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 interactive sections; it only applies to fully automated installs.
The config, and indeed the implementation, is 90% the same as that used by curtin.
Each key in the reporting mapping in the config 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.
webhook: report progress via POSTing JSON reports to a URL. Accepts the same configuration as curtin.
none: do not report progress. Only useful to inhibit the default output.
Examples:
The default configuration is:
reporting: builtin: type: print
Report to rsyslog:
reporting: central: type: rsyslog destination: @192.168.0.1
Suppress the default output:
reporting: builtin: type: none
Report to a curtin-style webhook:
reporting: hook: type: webhook endpoint: http://example.com/endpoint/path consumer_key: "ck_foo" consumer_secret: "cs_foo" token_key: "tk_foo" token_secret: "tk_secret" level: INFO
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 identity section (but then it's your responsibility to make sure that you can log into the installed system!).
FoundationsTeam/AutomatedServerInstalls/ConfigReference (last edited 2020-06-11 04:20:26 by mwhudson)