Automated server install reference

Automated Server Installs Config File Reference

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.


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


type: integer
default: no default

A future-proofing config file version field. Currently this must be “1”.


type: list of strings
default: []

A list of config keys to still show in the UI. So for example:

version: 1
 - network
 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.


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.


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.


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:


type: boolean
default: no

Whether to update or not.


type: string
default: "stable/ubuntu-$REL"

The channel to check for updates.


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:


type: string
default: "us"

Corresponds to the XKBLAYOUT setting.


type: string
default: ""

Corresponds to the XKBVARIANT setting.


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.


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.

For example, to run dhcp6 on a particular NIC:

  version: 2
      dhcp6: yes

Note that thanks to a bug, the version of subiquity released with 20.04 GA forces you to write this with an extra “network:” key like so:

    version: 2
        dhcp6: yes

Later versions support this syntax too for compatibility but if you can assume a newer version you should use the former.


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.


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, with one extension: the geoip key controls whether a geoip lookup is done.

The default is:

    preserve_sources_list: false
        - arches: [i386, amd64]
          uri: ""
        - arches: [default]
          uri: ""
    geoip: true

If geoip is true and the mirror to be used is the default, a request is made to and the mirror uri to be used changed to be 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:

        - arches: [default]
          uri: YOUR_MIRROR_GOES_HERE

To add a ppa:

            source: ppa:curtin-dev/test-archive


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

    name: lvm
    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:

    name: lvm
      serial: CT*
    name: disk
      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

If the “layout” feature is used to configure the disks, the “config” section will not be used.

As well as putting the list of actions under the ‘config’ key, the grub and swap curtin config items can be put here. So a storage section might look like:

        size: 0
        - type: disk
          id: disk0
          serial: ADATA_SX8200PNP_XXXXXXXXXXX
        - type: partition

The extensions to the curtin syntax are around disk selection and partition/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.

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

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
     ssd: yes
     size: largest

To match a Seagate drive:

 - type: disk
   id: data-disk
     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 config is more flexible:

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


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:


The real name for the user. This field is optional.


The user name to create.


The hostname for the system.


The password for the new user, crypted. This is required for use with sudo, even if SSH access is configured.


type: mapping, see below
default: see below
can be interactive: yes

Configure ssh for the installed system. A mapping that can contain keys:


type: boolean
default: false

Whether to install OpenSSH server in the target system.


type: list of strings
default: []

A list of SSH public keys to install in the initial user’s account.


type: boolean
default: true if authorized_keys is empty, false otherwise


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:

    - name: etcd
      channel: edge
      classic: false


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.


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


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


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.


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.


The default configuration is:

  type: print

Report to rsyslog:

  type: rsyslog
  destination: @

Suppress the default output:

  type: none

Report to a curtin-style webhook:

  type: webhook
  consumer_key: "ck_foo"
  consumer_secret: "cs_foo"
  token_key: "tk_foo"
  token_secret: "tk_secret"
  level: INFO


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


The type specified for the toggle sub-key under keyboard seems to be incorrect:

According to the JSON schema in, it must be a string, and that seems to correspond with the behaviour of the installer, which says, when toggle is set to null:

jsonschema.exceptions.ValidationError: None is not of type 'string'

Failed validating 'type' in schema['properties']['toggle']:
    {'type': 'string'}

On instance['toggle']:

I think this example is wrong:

If I use that (with an appropriate uri) I get an error:

TypeError: argument of type 'NoneType' is not iterable

I think the arches and uri should be part of the same list item, like this:

        - arches: [default]
          uri: YOUR_MIRROR_GOES_HERE

Thanks for the comments!

Ah yes this was a bug in the version released with 20.04 GA and I’ve updated the docs to say so. If you use the image from it should be better.

Quite right, also fixed.


The link to the netplan reference under the network section is incorrect, it currently links to but should link to


Thanks, must have mangled that when converting the wiki page to markdown. Fixed now!

1 Like

Here is late-commands only ?

runcmd is can be use ?

    - curtin in-target --target=/target -- apt-get -qq update


   - "apt-get -qq update"

more easily ?

runcmd is interpreted by cloud-init. If you put it in the cloud-config that also contains the autoinstall config, it will run before the installer starts. If you put it inside the user-data section of the autoinstall config, it will run on first boot of the installed system.

1 Like

autoinstall-generator is not work with d-i seed file. It’s seem to be Name, Username and Password only.

if we will provide preseed to user-data / cloud-init interpreter.

a lot of seed file will be convert and upgrade.

Easy to migrate.

  • convert d-i phase by phase
    • d-i anna/choose_modules
    • d-i apt-setup/backports
    • d-i apt-setup/local0/comment
    • d-i apt-setup/local0/key
    • d-i apt-setup/local0/repository
    • d-i apt-setup/local0/source
    • d-i apt-setup/multiarch
    • d-i apt-setup/restricted
    • d-i apt-setup/security_host
    • d-i apt-setup/security_path
    • d-i apt-setup/services-select
    • d-i apt-setup/universe
    • d-i apt-setup/use_mirror
    • d-i base-installer/install-recommends
    • d-i base-installer/kernel/image
    • d-i cdrom-detect/eject
    • d-i clock-setup/ntp
    • d-i clock-setup/ntp-server
    • d-i clock-setup/utc
    • d-i console-setup/ask_detect
    • d-i debian-installer/add-kernel-opts
    • d-i debian-installer/allow_unauthenticated
    • d-i debian-installer/country
    • d-i debian-installer/exit/halt
    • d-i debian-installer/exit/poweroff
    • d-i debian-installer/language
    • d-i debian-installer/locale
    • d-i finish-install/keep-consoles
    • d-i finish-install/reboot_in_progress
    • d-i grub-installer/bootdev
    • d-i grub-installer/only_debian
    • d-i grub-installer/password
    • d-i grub-installer/password-again
    • d-i grub-installer/password-crypted
    • d-i grub-installer/skip
    • d-i grub-installer/with_other_os
    • d-i hw-detect/load_firmware
    • d-i keyboard-configuration/toggle
    • d-i keyboard-configuration/xkb-keymap
    • d-i lilo-installer/skip
    • d-i live-installer/net-image
    • d-i localechooser/supported-locales
    • d-i mirror/country
    • d-i mirror/http/directory
    • d-i mirror/http/hostname
    • d-i mirror/http/mirror
    • d-i mirror/http/proxy
    • d-i mirror/protocol
    • d-i mirror/suite
    • d-i mirror/udeb/components
    • d-i mirror/udeb/suite
    • d-i netcfg/choose_interface
    • d-i netcfg/confirm_static
    • d-i netcfg/dhcp_failed
    • d-i netcfg/dhcp_hostname
    • d-i netcfg/dhcp_options
    • d-i netcfg/dhcp_timeout
    • d-i netcfg/dhcpv6_timeout
    • d-i netcfg/disable_autoconfig
    • d-i netcfg/enable
    • d-i netcfg/get_domain
    • d-i netcfg/get_gateway
    • d-i netcfg/get_hostname
    • d-i netcfg/get_ipaddress
    • d-i netcfg/get_nameservers
    • d-i netcfg/get_netmask
    • d-i netcfg/hostname
    • d-i netcfg/link_wait_timeout
    • d-i netcfg/wireless_wep
    • d-i network-console/authorized_keys_url
    • d-i network-console/password
    • d-i network-console/password-again
    • d-i partman-auto/choose_recipe
    • d-i partman-auto/disk
    • d-i partman-auto/expert_recipe
    • d-i partman-auto/expert_recipe_file
    • d-i partman-auto/init_automatically_partition
    • d-i partman-auto-lvm/guided_size
    • d-i partman-auto/method
    • d-i partman-auto-raid/recipe
    • d-i partman/choose_partition
    • d-i partman/confirm
    • d-i partman/confirm_nooverwrite
    • d-i partman/default_filesystem
    • d-i partman/early_command
    • d-i partman-lvm/confirm
    • d-i partman-lvm/confirm_nooverwrite
    • d-i partman-lvm/device_remove_lvm
    • d-i partman-md/confirm
    • d-i partman-md/device_remove_md
    • d-i partman/mount_style
    • d-i partman-partitioning/confirm_write_new_label
    • d-i passwd/make-user
    • d-i passwd/root-login
    • d-i passwd/root-password
    • d-i passwd/root-password-again
    • d-i passwd/root-password-crypted
    • d-i passwd/user-default-groups
    • d-i passwd/user-fullname
    • d-i passwd/username
    • d-i passwd/user-password
    • d-i passwd/user-password-again
    • d-i passwd/user-password-crypted
    • d-i passwd/user-uid
    • d-i pkgsel/include
    • d-i pkgsel/language-packs
    • d-i pkgsel/updatedb
    • d-i pkgsel/update-policy
    • d-i pkgsel/upgrade
    • d-i preseed/early_command
    • d-i preseeding
    • d-i preseed/late_command
    • d-i s390-dasd/auto-format
    • d-i s390-dasd/dasd
    • d-i s390-dasd/force-format
    • d-i s390-zfcp/zfcp
    • d-i time/zone
    • d-i user-setup/allow-password-weak
    • d-i user-setup/encrypt-home

If unknown or syntax error, might be error output for recheck and feedback.

If we have interpreter, we can make ubuntu autoinstall generator.

also from kickstart (ks)

To me, it was not obvious that the user-data was applied during install-time and the auto-install user-data key is the user-data applied at the first boot of the target system.

Maybe add a section clarifying this, since I believe this is a very common use-case.
Or, add this to the tutorial.

Andrew does a great job explaining the feature in more detail in an answer to a question I posted about this on

It would be helpful to show an example of an early-command and how you can use that to affect the install. In my case, I’d like to fork a small script to go ask the person installing what static IP and hostname they’d like to use, then use that to add an “identity” section to file for it to be used. I’m probably going to need to do the same thing for disk storage … assuming I can figure out how those commands work. – Thanks

This document doesn’t make it obvious how to set the timezone of the new system.

I’m not sure if this is the officially recommended method, but this worked for me:
timezone: America/New_York

I think this would be a good thing to add, as this is a common thing to want to configure on new systems.

I have not been able to determine a way (other than custom late-commands scripts) to tell the system to attempt automated geolocation to set the system time zone or to indicate that the hardware clock uses local time, rather that CUT (as might be done with systems that dual boot into MS .Windows). If either of these things are possible, instructions would be appreciated.

To follow up for anyone else looking how to do early-commands, especially if you need user input. In your yaml file do:

  - bash /cdrom/

That assumes your “” script sits in the top level dir of your ISO.

Then make sure in your script you always reference /dev/tty1, like:

echo "Hostname [$default_hostname]: " > /dev/tty1
read hostname < /dev/tty1

Note: because the script isn’t called in an environment with a real tty, you can’t do:

echo -n "Hostname [$default_hostname]: "
read hostname

to have the cursor wait on the same line. But you can accomplish that with a Perl script like:

hostname=$(perl -e '($p,$d)=@ARGV; open(W, ">/dev/tty1") or warn "W FAILED\n"; open(R, "</dev/tty1") or warn "R FAILED\n"; print W "$p [$d]: "; $h=<R>; chomp($h); $h ||= $d; print $h' "Hostname" "$default_hostname")

Of course, once you have that info, then you can write it out:

echo "identity:
  hostname: \"$hostname\"" >> /autoinstall.yaml

When your script ends, the autoinstall will reread the newly altered /autoinstall.yaml file and pick up your new directives. This technique is useful for grabbing the ethernet interface names and other things to in order to write out directives with values that can only be determined at install time.

Important note: You can only have 1 of each section (e.g. “identity”); so if you have both static and dynamic directives, you must put them all together in your script. Writing out the static info at the top of the yaml file, then using your early script to add another section with the same name with the dynamic values at the bottom of the yaml file will cause a crash. (Yep, learned that the hard way.)

Back to my nightmare of trying to figure out a complex storage layout with crash files that don’t tell me enough about what’s wrong…sigh.