.. _tutorial_intro-to-autoinstall: Introduction to autoinstall *************************** Automatic Ubuntu installation is performed with the autoinstall format. You might also know this feature as "unattended", "hands-off" or "preseeded" installation. This format is supported in the following installers: * Ubuntu Server, version 20.04 and later * Ubuntu Desktop, version 23.04 and later 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 (also known as d-i). Autoinstalls differ from preseeds in the following ways: * The format is different: autoinstalls use YAML instead of the preseed debconf-set-selections. * When the answer to a question is not present in a preseed, d-i stops and asks the user for input. By comparison, if there is any autoinstall configuration at all, the autoinstall takes the default for any unanswered question (and fails if there is no default). * You can designate particular sections in the autoinstall configuration as "interactive", which means the installer will still stop and ask about those. Providing the autoinstall configuration ======================================= There are 2 ways to provide the autoinstall configuration: * Provide :external+cloud-init:ref:`#cloud-config user-data` containing ``autoinstall:`` configuration directives to cloud-init at boot time * Directly on the install media Autoinstall by way of cloud-config ---------------------------------- The suggested way of providing autoinstall config to the Ubuntu installer is via cloud-init. This allows the configuration to be applied to the installer without having to modify the install media. 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 :external+cloud-init:ref:`datasource_nocloud` data source. When providing autoinstall via cloud-init, the autoinstall config is provided as :external+cloud-init:ref:`user_data_formats-cloud_config`. This means we need a :code:`#cloud-config` header. The autoinstall directives are placed under a top level :code:`autoinstall:` key, like so: .. code-block:: yaml #cloud-config autoinstall: version: 1 .... .. note:: :external+cloud-init:ref:`user_data_formats-cloud_config` files must contain the ``#cloud-config`` header to be recognized as a valid cloud config data file. Autoinstall on the install media -------------------------------- Another option for supplying autoinstall to the Ubuntu installer is to place a file named :code:`autoinstall.yaml` on the install media itself. There are two potential locations that subiquity will check for the :code:`autoinstall.yaml` file: * At the root of the "CD-ROM". When you write the installation ISO to a USB Flash Drive, this can be done by copying the :code:`autoinstall.yaml` to the partition containing the contents of the ISO - i.e., in the directory containing the ``casper`` sub-directory. * On the rootfs of the installation system - this option will typically require modifying the installation ISO and is not suggested, but is supported. Alternatively, you can pass the location of the autoinstall file on the kernel command line via the :code:`subiquity.autoinstallpath` parameter, where the path is relative to the rootfs of the installation system. For example: * :code:`subiquity.autoinstallpath=path/to/autoinstall.yaml` .. note:: Directly specifying autoinstall as a :code:`autoinstall.yaml` file does not require a :code:`#cloud-config` header, and does not use a top level ``autoinstall:`` key. The autoinstall directives are placed at the top level. For example: .. code-block:: yaml version: 1 .... Order precedence of the autoinstall locations ============================================= Since there are many ways to specify the autoinstall file, it may happen that multiple locations are specified at once. Subiquity will look for the autoinstall file in the following order and pick the first existing one: 1. Kernel command line 2. Root of the installation system 3. Cloud Config 4. Root of the CD-ROM (ISO) Cloud-init and autoinstall interaction ====================================== Cloud-init runs in both the ephemeral system (during install) and in the target system during first boot. Cloud-init then becomes inert for every subsequent reboot. While cloud-init may provide the autoinstall configuration to the Ubuntu installer, it does not process the autoinstall directives itself. To modify the ephemeral system with cloud-init, any :external+cloud-init:ref:`#cloud-config module schema keys` can be provided. If instead cloud-init directives are intended to modify the system being installed, they must appear under a :ref:`ai-user-data` section under ``autoinstall:``. .. code-block:: yaml #cloud-config # cloud-init directives may optionally be specified here. # These directives affect the ephemeral system performing the install. autoinstall: # autoinstall directives must be specified here, not directly at the # top level. These directives are processed by the Ubuntu Installer, # and configure the target system to be installed. user-data: # cloud-init directives may also be optionally be specified here. # These directives also affect the target system to be installed, # and are processed on first boot. Zero-touch deployment with autoinstall ====================================== The Ubuntu Installer contains a safeguard, intended to prevent USB Flash Drives with an :code:`autoinstall.yaml` file from wiping out the wrong system. Before the Ubuntu Installer actually makes changes to the target system, a prompt is shown. :: start: subiquity/Meta/status_GET Confirmation is required to continue. Add 'autoinstall' to your kernel command line to avoid this Continue with autoinstall? (yes|no) To bypass this prompt, arrange for the argument :code:`autoinstall` to be present on the kernel command line. Creating an autoinstall config ============================== When any system is installed using the Ubuntu installer, an autoinstall file for repeating the install is created at :code:`/var/log/installer/autoinstall-user-data`. The structure of an autoinstall configuration ============================================= See the :ref:`ai` for full details on the supported autoinstall directives. A minimal autoinstall configuration in :external+cloud-init:ref:`user_data_formats-cloud_config` format looks like: .. code-block:: yaml #cloud-config autoinstall: version: 1 identity: hostname: hostname username: username password: $crypted_pass Here is an example file that shows off most of the autoinstall directives: .. parsed-literal:: #cloud-config autoinstall: :ref:`ai-version`: 1 :ref:`ai-reporting`: hook: type: webhook endpoint: http\://example.com/endpoint/path :ref:`ai-early-commands`: - ping -c1 198.162.1.1 :ref:`ai-locale`: en_US :ref:`ai-keyboard`: layout: gb variant: dvorak :ref:`ai-network`: network: version: 2 ethernets: enp0s25: dhcp4: yes enp3s0: {} enp4s0: {} bonds: bond0: dhcp4: yes interfaces: - enp3s0 - enp4s0 parameters: mode: active-backup primary: enp3s0 :ref:`ai-proxy`: http\://squid.internal:3128/ :ref:`ai-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 :ref:`ai-storage`: layout: name: lvm :ref:`ai-identity`: hostname: hostname username: username password: $crypted_pass :ref:`ai-ssh`: install-server: yes authorized-keys: - $key allow-pw: no :ref:`ai-snaps`: - name: go channel: 1.20/stable classic: true :ref:`ai-debconf-selections`: | bind9 bind9/run-resolvconf boolean false :ref:`ai-packages`: - libreoffice - dns-server^ :ref:`ai-user-data`: disable_root: false :ref:`ai-late-commands`: - sed -ie 's/GRUB_TIMEOUT=.\*/GRUB_TIMEOUT=30/' /target/etc/default/grub :ref:`ai-error-commands`: - tar c /var/log/installer | nc 192.168.0.1 1000 Error handling ============== Progress through the installer is reported via the :ref:`ai-reporting` system, including errors. In addition, when a fatal error occurs, the :ref:`ai-error-commands` are executed and the traceback printed to the console. The server then just waits.