Automated Server installation

Important:
This documentation has been moved and is now being maintained as part of the Ubuntu Installer documentation. For the up-to-date version of this content, please refer to this version instead.

Since version 20.04, the server installer supports automated installation mode (autoinstallation for short). You might also know this feature as unattended, hands-off, or preseeded installation.

Autoinstallation lets you answer all those configuration questions ahead of time with an autoinstall config, and lets the installation process run without any interaction.

Differences from debian-installer preseeding

Preseeds are the way to automate an installer based on debian-installer (a.k.a. d-i).

Autoinstalls for the new server installer differ from preseeds in the following main ways:

  • The format is completely different (cloud-init config, usually YAML, vs. debconf-set-selections format).
  • When the answer to a question is not present in a preseed, d-i stops and asks the user for input. Autoinstalls are not like this: by default, if there is any autoinstall config at all, the installer takes the default for any unanswered question (and fails if there is no default).
    • You can designate particular sections in the config as “interactive”, which means the installer will still stop and ask about those.

Provide the autoinstall config via cloud-init

The autoinstall config is provided via cloud-init configuration, which is almost endlessly flexible. In most scenarios, the easiest way will be to provide user data via the NoCloud datasource.

The autoinstall config should be provided under the autoinstall key in the config. For example:

#cloud-config
autoinstall:
  version: 1
  ...

Run a truly automatic autoinstall

Even if a fully non-interactive autoinstall config is found, the server installer will ask for confirmation before writing to the disks unless autoinstall is present on the kernel command line. This is to make it harder to accidentally create a USB stick that will reformat the machine it is plugged into at boot. Many autoinstalls will be done via netboot, where the kernel command line is controlled by the netboot config – just remember to put autoinstall in there!

Quick start

So you just want to try it out? Well we have the page for you.

Create an autoinstall config

When any system is installed using the server installer, an autoinstall file for repeating the install is created at /var/log/installer/autoinstall-user-data.

Translate a preseed file

If you have a preseed file already, the autoinstall-generator snap can help translate that preseed data to an autoinstall file. See this discussion on the autoinstall generator tool for more details on how to set this up.

The structure of an autoinstall config

The autoinstall config has full documentation.

Technically speaking, the config is not defined as a textual format, but cloud-init config is usually provided as YAML so that is the syntax the documentation uses. A minimal config consists of:

version: 1
identity:
    hostname: hostname
    username: username
    password: $crypted_pass

However, here is a more complete example file that shows off most features:

version: 1
reporting:
    hook:
        type: webhook
        endpoint: http://example.com/endpoint/path
early-commands:
    - ping -c1 198.162.1.1
locale: en_US
keyboard:
    layout: gb
    variant: dvorak
network:
    network:
        version: 2
        ethernets:
            enp0s25:
               dhcp4: yes
            enp3s0: {}
            enp4s0: {}
        bonds:
            bond0:
                dhcp4: yes
                interfaces:
                    - enp3s0
                    - enp4s0
                parameters:
                    mode: active-backup
                    primary: enp3s0
proxy: http://squid.internal:3128/
apt:
    primary:
        - arches: [default]
          uri: http://repo.internal/
    sources:
        my-ppa.list:
            source: "deb http://ppa.launchpad.net/curtin-dev/test-archive/ubuntu $RELEASE main"
            keyid: B59D 5F15 97A5 04B7 E230  6DCA 0620 BBCF 0368 3F77
storage:
    layout:
        name: lvm
identity:
    hostname: hostname
    username: username
    password: $crypted_pass
ssh:
    install-server: yes
    authorized-keys:
      - $key
    allow-pw: no
snaps:
    - name: go
      channel: 1.14/stable
      classic: true
debconf-selections: |
    bind9      bind9/run-resolvconf    boolean false
packages:
    - libreoffice
    - dns-server^
user-data:
    disable_root: false
late-commands:
    - sed -ie 's/GRUB_TIMEOUT=.\*/GRUB_TIMEOUT=30/' /target/etc/default/grub
error-commands:
    - tar c /var/log/installer | nc 192.168.0.1 1000

Many keys and values correspond straightforwardly to questions the installer asks (e.g. keyboard selection). See the reference for details of those that do not.

Error handling

Progress through the installer is reported via the reporting system, including errors. In addition, when a fatal error occurs, the error-commands are executed and the traceback printed to the console. The server then just waits.

Interactions between autoinstall and cloud-init

Delivery of autoinstall

Cloud-config can be used to deliver the autoinstall data to the installation environment. The autoinstall quickstart has an example of writing the autoinstall config.

Note that autoinstall is processed by Subiquity (not cloud-init), so please direct defects in autoinstall behavior and bug reports to Subiquity.

The installation environment

At install time, the live-server environment is just that: a live but ephemeral copy of Ubuntu Server. This means that cloud-init is present and running in that environment, and existing methods of interacting with cloud-init can be used to configure the live-server ephemeral environment. For example, any #cloud-config user data keys are presented to the live-server containing ssh_import_id, then SSH keys will be added to the authorized_keys list for the ephemeral environment.

First boot configuration of the target system

Autoinstall data may optionally contain a user data sub-section, which is cloud-config data that is used to configure the target system on first boot.

Subiquity itself delegates some configuration items to cloud-init, and these items are processed on first boot.

Starting with Ubuntu 22.10, once cloud-init has performed this first boot configuration, it will disable itself as cloud-init completes configuration in the target system on first boot.

Possible future directions

We might want to extend the ‘match specs’ for disks to cover other ways of selecting disks.

2 Likes

I was about to implement an extension to the curtin partition size setting and saw that it’s already possible to use percentage values. This is missing on the documentation page. I’m not suggesting a text as you as a native speaker will most likely be much quicker and more accurate writing one.

Hm it was documented under https://ubuntu.com/server/docs/install/autoinstall-reference#storage but it certainly wasn’t very clear. I’ve tried to make it more prominent.

And one more thing. :slight_smile: Atm there is no automated way to create a RAID1 if you have two disks. I guess that quite a few users will start like I did in the beginning: select “Create software RAID (md)”, select both disks and be surprised it doesn’t work. There is no hint at all that you have to go a quite tedious route: create GPT/grub and unformated partitions on both disks to create the raid with them and then add another partition on top of it. Absolutely clear once you know it but beforehand…
This documentation is outdated: https://ubuntu.com/server/docs/installation-advanced
So, it would be cool to have a guided installation that sets up a raid 1. :tada:

It’s clear now, thank you.

Alternatively there is a snap, autoinstall-editor, that can be used to either edit or create from scratch an autoinstall config 

I can not find any autoinstall-editor snap
how to install this tool ?

Look at the line in bold directly above your reference to autoinstall-editor

1 Like

There is a minor bug on this page that cost me several days and almost drove me crazy:

primary:
- arches: [default]
- uri: http://repo.internal/

there must not be a hyphen in front of the uri line!

Argh, sorry about that! It’s fixed now, thanks for letting us know :slight_smile:

1 Like

Hi, I now have what I believe to be a correct user-data, but the system keeps crashing during install.
I get an error message “Sorry, there was a problem completing the installation. Information is being collected from the system that will help the developers diagnose the report.” Here is a tgz of my logs. This happens both on a virtual an on a real machine. I guess that all the necessary version information is contained in the log files, if not, please let me now. My user-data is below.
Any idea what is going wrong?

#cloud-config
autoinstall:
  version: 1
  identity: 
    hostname: ubuntu-install 
    username: xxx
    password: yyy
    realname: AA
  keyboard:
    layout: us
    variant: ''
  locale: en_GB
  interactive-sections:
    - storage
  apt:
    primary:
      - arches: [default]
        uri: http://ubuntu.mirror.lrz.de/
  storage:
    layout:
      name: direct

Anybody? There must be somebody who managed to get this working…

Do we have an ETA on the availability of the autoinstall-editor snap package? Is there something that we could follow to know its status?

Sorry for missing this. The link to your logs no longer works so I can’t help now though :frowning:

Hopefully by the release of Groovy in October. But there’s a chance it might not make it at the rate things are going.

1 Like

It would be good if the autoinstall config could be taken from the root directory of the initial ramdisk (initrd) the same way that preseed.cfg could be supplied like this. This way tools such as virt-install with its --initrd-inject option can continue to work easily.

2 Likes

I had this implemented at one point but took it out again because I didn’t have any use cases. Looks like we have one now!

3 Likes

Can the initial user be only the ‘root’ user? We prefer to set up user accounts via Ansible after the initial base installation. This is because user accounts are handled via SSSD + AD authentication, and we do not have local user accounts set up in /etc/passwd.
If needed, we could create an initial local user account, and then delete it in the ‘late-commands’ section, but would prefer to not create it at all.

This is more a cloud-init question than anything else, but I think you can do it with something like this (not tested):

#cloud-config
autoinstall:
  user-data:
    disable_root: false
    ssh_authorized_keys:
    - $KEY