ConfigReference
8835
Comment:
|
10639
|
Deletions are marked like this. | Additions are marked like this. |
Line 27: | Line 27: |
== interactive-sections == '''type:''' list of strings <<BR>> '''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 does 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. |
|
Line 32: | Line 55: |
<<BR>> '''can be interactive:''' no |
|
Line 35: | Line 60: |
Line 40: | Line 66: |
<<BR>> '''can be interactive:''' yes |
|
Line 48: | Line 76: |
<<BR>> '''can be interactive:''' yes |
|
Line 56: | Line 86: |
<<BR>> '''can be interactive:''' yes |
|
Line 64: | Line 96: |
<<BR>> '''can be interactive:''' yes |
|
Line 72: | Line 106: |
<<BR>> '''can be interactive:''' yes |
|
Line 80: | Line 116: |
<<BR>> '''can be interactive:''' yes |
|
Line 179: | Line 217: |
Configure the initial user for the system. A mapping that can contain keys: |
<<BR>> '''can be interactive:''' yes Configure the initial user for the system. This is the only config key that must be present (unless cloud-init is present, in which case it is optional). A mapping that can contain keys: |
Line 191: | Line 233: |
'''default:''' do not install openssh-server | '''default:''' `{install_server: no, authorized_keys: [], allow_pw: yes}` <<BR>> '''can be interactive:''' yes |
Line 204: | Line 248: |
<<BR>> '''can be interactive:''' yes |
|
Line 212: | Line 258: |
<<BR>> '''can be interactive:''' no |
|
Line 220: | Line 268: |
<<BR>> '''can be interactive:''' no |
|
Line 228: | Line 278: |
<<BR>> '''can be interactive:''' no |
|
Line 236: | Line 288: |
<<BR>> '''can be interactive:''' no |
|
Line 244: | Line 298: |
<<BR>> '''can be interactive:''' no |
|
Line 292: | Line 348: |
== cloud-init == '''type:''' mapping <<BR>> '''default:''' `{}` <<BR>> '''can be interactive:''' no Provide cloud-init config which will be merged with the config the installer produces. If you supply this, you don't need to supply an identity section. |
This document is entirely a description of something that does not yet exist |
Automated Server Installs Config File Reference
This document is entirely a description of something that does not yet exist |
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
A schema for the config file should be written down at some point.
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 does 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.
early_commands
type: 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
The locale to configure for the installer.
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.
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
default: no proxy
can be interactive: yes
The proxy to configure both during installation and for apt and for snapd in the target system.
mirror
type: URL
default: http://archive.ubuntu.com/ubuntu or http://ports.ubuntu.com/ubuntu-ports depending on architecture
can be interactive: yes
The archive mirror to use.
filesystem
type: mapping, see below
default: use "lvm" layout in a single disk system, no default in a multiple disk system
can be interactive: yes
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.
Supported layouts
The two supported layouts at the time of writing are "lvm" and "disk".
filesystem: layout: name: lvm filesystem: layout: 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: layout: name: lvm match: serial: CT* filesystem: layout: name: disk match: ssd: yes
(you can just say "match: {}" to match an arbitrary disk)
The default in a single disk system is to use the lvm layout. There is no default in a system with multiple disks.
action-based config
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.
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 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.
A match spec supports the following keys:
model: foo: matches a disk where ID_VENDOR=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: 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
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, or using min/priority/max as in d-i: (XXX I don't actually understand how min/priority/max works in d-i).
- type: partition id: data-partition device: data-disk size: 75% - type: partition id: boot-partition device: boot-disk size: min: 512M priority: 600M max: 2G
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 cloud-init is present, in which case it is optional).
A mapping that can contain keys:
realname
username
hostname
password
ssh
type: mapping, see below
default: {install_server: no, authorized_keys: [], allow_pw: yes}
can be interactive: yes
Configure ssh for the installed system. A mapping that can contain keys:
install_server
authorized_keys
allow_pw
snaps
type: list
default: install no extra snaps
can be interactive: yes
Snaps to install, in the format "$snap_name/$channel".
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.
late_commands
type: 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.
error_commands
type: 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. Each key in the reporting mapping in the config defines a destination, where the type sub-key is one of:
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's option, documented at https://curtin.readthedocs.io/en/latest/topics/reporting.html.
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
cloud-init
type: mapping
default: {}
can be interactive: no
Provide cloud-init config which will be merged with the config the installer produces. If you supply this, you don't need to supply an identity section.
FoundationsTeam/AutomatedServerInstalls/ConfigReference (last edited 2020-06-11 04:20:26 by mwhudson)