curtin documentation · chapter 2 curtin conﬁguration curtin exposes a number of conﬁguration...

curtin DocumentationRelease 21.2

Scott Moser

May 13, 2021

Contents

1 Overview 31.1 Stages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Curtin Configuration 72.1 Configuration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3 APT Source 213.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223.3 Common snippets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233.4 Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243.5 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243.6 apt preserve_sources_list setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

4 Networking 274.1 Configuration Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274.2 Multi-layered configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344.3 More Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

5 Storage 375.1 Configuration Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375.2 Additional Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

6 Curthooks / New OS Support 636.1 Image provided curtin-hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636.2 Running built-in hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646.3 Networking configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646.4 Storage configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646.5 System boot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646.6 finalize hook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

7 Reporting 657.1 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667.3 Webhook Reporter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667.4 Journald Reporter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667.5 Development / Debug Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

i

7.6 Legacy Reporter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

8 Hacking on curtin 698.1 Do these things once . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698.2 Do these things for each feature or bug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

9 Integration Testing 719.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719.2 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729.3 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729.4 Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739.5 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739.6 Environment ‘boolean’ values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769.7 Test Class Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

10 Indices and tables 79

ii

curtin Documentation, Release 21.2

This is ‘curtin’, the curt installer. It is blunt, brief, snappish, snippety and unceremonious. Its goal is to install anoperating system as quick as possible.

Contents:

Contents 1


2 Contents

CHAPTER 1

Overview

Curtin is intended to be a bare bones “installer”. Its goal is to take data from a source, and get it onto disk as quick aspossible and then boot it. The key difference from traditional package based installers is that curtin assumes the thingits installing is intelligent and will do the right thing.

1.1 Stages

A usage of curtin will go through the following stages:

• Install Environment boot

• Early Commands

• Partitioning

• Network Discovery and Setup

• Extraction of sources

• Hook for installed OS to customize itself

• Final Commands

1.1.1 Install Environment boot

At the moment, curtin doesn’t address how the system that it is running on is booted. It could be booted from a live-cdor from a pxe boot environment. It could even be booted off a disk in the system (although installation to that diskwould probably break things).

Curtin’s assumption is that a fairly rich Linux (Ubuntu) environment is booted.

1.1.2 Command Environment

Stages and commands invoked by curtin always have the following environment variables defined.

3


• WORKING_DIR: This is for inter-command state. It will be the same directory for each command run and willonly be deleted at the end of the install. Files referenced in other environment variables will be in this directory.

• TARGET_MOUNT_POINT: The path in the filesystem where the target filesystem will be mounted.

• OUTPUT_NETWORK_CONFIG: After the network discovery stage, this file should contain networking configinformation that should then be written to the target.

• OUTPUT_FSTAB: After partitioning and filesystem creation, this file will contain fstab(5) style content repre-senting mounts.

• CONFIG: This variable contains a path to a yaml formatted file with the fully rendered config.

1.1.3 Early Commands

Early commands are executed on the system, and non-zero exit status will terminate the installation process. Thesecommands are intended to be used for things like

• module loading

• hardware setup

• environment setup for subsequent stages of curtin.

Config Example:

early_commands:05_load_loop: [modprobe, loop]99_update: apt-get update && apt-get dist-upgrade

1.1.4 Partitioning

Partitioning covers setting up filesystems on the system. A series of commands are run serially in order. At the end,a fstab formatted file must be populated in OUTPUT_FSTAB that contains mount information, and the filesystems areexpected to be mounted at the TARGET_MOUNT_POINT.

Any commands can be used to create this filesystem, but curtin contains some tools to facilitate with this process.

Config Example:

partitioning_commands:10_wipe_filesystems: curtin wipe --quick --all-unused-disks50_setup_raid: curtin disk-setup --all-disks raid0 /

1.1.5 Network Discovery

Networking configuration is discovered in the ‘network’ stage. The default command run at this stage is curtinnet-meta auto. After execution, it will write the discovered networking to the file specified in the environmentvariable OUTPUT_NETWORK_CONFIG. The format of this file is as described in Networking.

If curtin’s config has a network section, the net-meta will simply parrot the data to the output file. If there is no networksection, then its default behavior is to copy existing config from the running environment.

Note, that as with fstab, this file is not copied verbatim to the target filesystem, but rather made available to the OScustomization stage. That stage may just copy the file verbatim, but may also parse it, and apply the settings.

4 Chapter 1. Overview


1.1.6 Extraction of sources

Sources are the things to install. Curtin prefers to install root filesystem tar files.

Config Example:

sources:05_primary: http://cloud-images.ubuntu.com/releases/precise/release/ubuntu-12.04-→˓server-cloudimg-amd64-root.tar.gz

Given the source above, curtin will essentially do a:

wget $URL | tar -Sxvzf

1.1.7 Final Commands

Config Example:

final_commands:05_callhome_finished: wget http://example.com/i-am-done

1.1. Stages 5


6 Chapter 1. Overview

CHAPTER 2

Curtin Configuration

Curtin exposes a number of configuration options for controlling Curtin behavior during installation.

2.1 Configuration options

Curtin’s top level config keys are as follows:

• apt_mirrors (apt_mirrors)

• apt_proxy (apt_proxy)

• block-meta (block)

• curthooks (curthooks)

• debconf_selections (debconf_selections)

• disable_overlayroot (disable_overlayroot)

• grub (grub)

• http_proxy (http_proxy)

• install (install)

• kernel (kernel)

• kexec (kexec)

• multipath (multipath)

• network (network)

• pollinate (pollinate)

• power_state (power_state)

• proxy (proxy)

• reporting (reporting)

7


• restore_dist_interfaces: (restore_dist_interfaces)

• sources (sources)

• stages (stages)

• storage (storage)

• swap (swap)

• system_upgrade (system_upgrade)

• write_files (write_files)

2.1.1 apt_mirrors

Configure APT mirrors for ubuntu_archive and ubuntu_security

ubuntu_archive:

ubuntu_security:

If the target OS includes /etc/apt/sources.list, Curtin will replace the default values for each key set with the suppliedmirror URL.

Example:

apt_mirrors:ubuntu_archive: http://local.archive/ubuntuubuntu_security: http://local.archive/ubuntu

2.1.2 apt_proxy

Curtin will configure an APT HTTP proxy in the target OS

apt_proxy:

Example:

apt_proxy: http://squid.mirror:3267/

2.1.3 block-meta

Configure how Curtin selects and configures disks on the target system without providing a custom configuration(mode=simple).

devices:

The devices parameter is a list of block device paths that Curtin may select from with choosing where to install theOS.

boot-partition:

The boot-partition parameter controls how to configure the boot partition with the following parameters:

enabled:

Enabled will forcibly setup a partition on the target device for booting.

format:

8 Chapter 2. Curtin Configuration


Specify the partition format. Some formats, like uefi and prep are restricted by platform characteristics.

fstype:

Specify the filesystem format on the boot partition.

label:

Specify the filesystem label on the boot partition.

Example:

block-meta:devices:

- /dev/sda- /dev/sdb

boot-partition:- enabled: True

format: gptfstype: ext4label: my-boot-partition

2.1.4 curthooks

Configure how Curtin determines what Curthooks / New OS Support to run during the installation process.

mode:

The default mode is auto.

In auto mode, curtin will execute curthooks within the image if present. For images without curthooks inside, curtinwill execute its built-in hooks.

Currently the built-in curthooks support the following OS families:

• Ubuntu

• Centos

When specifying builtin, curtin will only run the curthooks present in Curtin ignoring any curthooks that may bepresent in the target operating system.

When specifying target, curtin will attempt run the curthooks in the target operating system. If the target does NOTcontain any curthooks, then the built-in curthooks will be run instead.

Any errors during execution of curthooks (built-in or target) will fail the installation.

Example:

# ignore any target curthookscurthooks:

mode: builtin

# Only run target curthooks, fall back to built-incurthooks:

mode: target

2.1.5 debconf_selections

Curtin will update the target with debconf set-selection values. Users will need to be familiar with the package debconfoptions. Users can probe a packages’ debconf settings by using debconf-get-selections.

2.1. Configuration options 9


selection_name:

debconf-set-selections is in the form:

Example:

debconf_selections:set1: |cloud-init cloud-init/datasources multiselect MAASlxd lxd/bridge-name string lxdbr0

set2: lxd lxd/setup-bridge boolean true

2.1.6 disable_overlayroot

Curtin disables overlayroot in the target by default.

disable_overlayroot:

Example:

disable_overlayroot: False

2.1.7 grub

Curtin configures grub as the target machine’s boot loader. Users can control a few options to tailor how the systemwill boot after installation.

install_devices:

Specify a list of devices onto which grub will attempt to install.

replace_linux_default:

Controls whether grub-install will update the Linux Default target value during installation.

update_nvram:

Certain platforms, like uefi and prep systems utilize NVRAM to hold boot configuration settings which controlthe order in which devices are booted. Curtin by default will enable NVRAM updates to boot configuration settings.Users may disable NVRAM updates by setting the update_nvram value to False.

probe_additional_os:

This setting controls grub’s os-prober functionality and Curtin will disable this feature by default to prevent grub fromsearching for other operating systems and adding them to the grub menu.

When False, curtin writes “GRUB_DISABLE_OS_PROBER=true” to target system in /etc/default/grub.d/50-curtin-settings.cfg. If True, curtin won’t modify the grub configuration value in the target system.

terminal:

Configure target system grub option GRUB_TERMINAL terminal value which is written to /etc/default/grub.d/50-curtin-settings.cfg. Curtin does not attempt to validate this string, grub2 has many values that it accepts and the list isplatform dependent. If terminal is not provided, Curtin will set the value to ‘console’. If the terminal value is‘unmodified’ then Curtin will not set any value at all and will use Grub defaults.

reorder_uefi:



Curtin is typically used with MAAS where the systems are configured to boot from the network leaving MAAS incontrol. On UEFI systems, after installing a bootloader the systems BootOrder may be updated to boot from the newentry. This breaks MAAS control over the system as all subsequent reboots of the node will no longer boot over thenetwork. Therefore, if reorder_uefi is True curtin will modify the UEFI BootOrder settings to place the currentlybooted entry (BootCurrent) to the first option after installing the new target OS into the UEFI boot menu. The result isthat the system will boot from the same device that it booted to run curtin; for MAAS this will be a network device.

On some UEFI systems the BootCurrent entry may not be present. This can cause a system to not boot to the samedevice that it was previously booting. If BootCurrent is not present, curtin will update the BootOrder such that allNetwork related entries are placed before the newly installed boot entry and all other entries are placed at the end.This enables the system to network boot first and on failure will boot the most recently installed entry.

This setting is ignored if update_nvram is False.

reorder_uefi_force_fallback:

The fallback reodering mechanism is only active if BootCurrent is not present in the efibootmgr output. The fallbackreordering method may be enabled even if BootCurrent is present if reorder_uefi_force_fallback is True.

This setting is ignored if update_nvram or reorder_uefi are False.

remove_duplicate_entries:

When curtin updates UEFI NVRAM it will remove duplicate entries that are present in the UEFI menu. If you do notwish for curtin to remove duplicate entries setting remove_duplicate_entries to False.

This setting is ignored if update_nvram is False.

Example:

grub:install_devices:

- /dev/sda1replace_linux_default: Falseupdate_nvram: Trueterminal: serialremove_duplicate_entries: True

Default terminal value, GRUB_TERMINAL=console:


- /dev/sda1

Don’t set GRUB_TERMINAL in target:


- /dev/sda1terminal: unmodified

Allow grub to probe for additional OSes:

grub:install_devices:- /dev/sda1

probe_additional_os: True

Avoid writting any settings to etc/default/grub.d/50-curtin-settings.cfg:



grub:install_devices:- /dev/sda1

probe_additional_os: Trueterminal: unmodified

Enable Fallback UEFI Reordering:

grub:reorder_uefi: truereorder_uefi_force_fallback: true

2.1.8 http_proxy

Curtin will export http_proxy value into the installer environment. Deprecated: This setting is deprecated in favorof proxy below.

http_proxy:

Example:

http_proxy: http://squid.proxy:3728/

2.1.9 install

Configure Curtin’s install options.

log_file:

Curtin logs install progress by default to /var/log/curtin/install.log

error_tarfile:

If error_tarfile is not None and curtin encounters an error, this tarfile will be created. It includes logs, configurationand system info to aid triage and bug filing. When unset, error_tarfile defaults to /var/log/curtin/curtin-logs.tar.

post_files:

Curtin by default will post the log_file value to any configured reporter.

save_install_config:

Curtin will save the merged configuration data into the target OS at the path of save_install_config. Thisdefaults to /root/curtin-install-cfg.yaml

save_install_logs:

Curtin will copy the install log to a specific path in the target filesystem. This defaults to /root/install.log

target:

Control where curtin mounts the target device for installing the OS. If this value is unset, curtin picks a suitable pathunder a temporary directory. If a value is set, then curtin will utilize the target value instead.

unmount: disabled

If this key is set to the string ‘disabled’ then curtin will not unmount the target filesystem when install is complete.This skips unmounting in all cases of install success or failure.

Example:



install:log_file: /tmp/install.logerror_tarfile: /var/log/curtin/curtin-error-logs.tarpost_files:

- /tmp/install.log- /var/log/syslog

save_install_config: /root/myconf.yamlsave_install_log: /var/log/curtin-install.logtarget: /my_mount_pointunmount: disabled

2.1.10 kernel

Configure how Curtin selects which kernel to install into the target image. If kernel is not configured, Curtin willuse the default mapping below and determine which package value by looking up the current release and currentkernel version running.

fallback-package:

Specify a kernel package name to be used if the default package is not available.

mapping:

Default mapping for Releases to package names is as follows:

precise:3.2.0:3.5.0: -lts-quantal3.8.0: -lts-raring3.11.0: -lts-saucy3.13.0: -lts-trusty

trusty:3.13.0:3.16.0: -lts-utopic3.19.0: -lts-vivid4.2.0: -lts-wily4.4.0: -lts-xenial

xenial:4.3.0:4.4.0:

package:

Specify the exact package to install in the target OS.

Example:

kernel:fallback-package: linux-image-genericpackage: linux-image-generic-lts-xenialmapping:- xenial:

- 4.4.0: -my-custom-kernel

2.1.11 kexec

Curtin can use kexec to “reboot” into the target OS.



mode:

Enable rebooting with kexec.

Example:

kexec:mode: "on"

2.1.12 multipath

Curtin will detect and autoconfigure multipath by default to enable boot for systems with multipath. Curtin does notapply any advanced configuration or tuning, rather it uses distro defaults and provides enough configuration to enablebooting.

mode:

Defaults to auto which will configure enough to enable booting on multipath devices. Disabled will prevent curtinfrom installing or configuring multipath.

overwrite_bindings:

If overwrite_bindings is True then Curtin will generate new bindings file for multipath, overriding any existingbinding in the target image.

Example:

multipath:mode: autooverwrite_bindings: True

2.1.13 network

Configure networking (see Networking section for details).

network_option_1:

Example:

network:version: 1config:

- type: physicalname: eth0mac_address: "c0:d6:9f:2c:e8:80"subnets:- type: dhcp4

2.1.14 pollinate

Configure pollinate user-agent

Curtin will automatically include Curtin’s version in the pollinate user-agent. If a MAAS server is being used, Curtinwill query the MAAS version and include this value as well.

user_agent: [ | ]



Mapping is a dictionary of key value pairs which will result in the string ‘key/value’ being present in the pollinateuser-agent string sent to the pollen server.

Setting the user_agent value to false will disable writting of the user-agent string.

Example:

pollinate:user_agent:

curtin: 17.1-33-g92fbc491maas: 2.1.5+bzr5596-0ubuntu1machine: bob27app: 63.12

pollinate:user_agent: false

2.1.15 power_state

Curtin can configure the target machine into a specific power state after completing an installation. Default is to donothing.

delay:

Curtin will wait delay seconds before changing the power state.

mode:

Curtin will transition the node into one of the new states listed.

halt will stop a machine, but may not cut the power to the system. poweroff will stop a machine and request itshut off the power. reboot will perform a platform reset.

message:

The message string will be broadcast to system consoles prior to power state change.

Example:

power_state:mode: poweroffdelay: 5message: Bye Bye

2.1.16 proxy

Curtin will put http_proxy, https_proxy and no_proxy into its install environment. This is in affect forcurtin’s process and subprocesses.

proxy: A dictionary containing http_proxy, https_proxy, and no_proxy.

Example:

proxy:http_proxy: http://squid.proxy:3728/https_proxy: http://squid.proxy:3728/no_proxy: localhost,127.0.0.1,10.0.2.1



2.1.17 reporting

Configure installation reporting (see Reporting section for details).

Example:

reporting:maas:level: DEBUGtype: webhookendpoint: http://localhost:8000/

2.1.18 restore_dist_interfaces

Curtin can restore a copy of /etc/network/interfaces built in to cloud images.

restore_dist_interfaces:

If True, then Curtin will restore the interfaces file into the target.

Example:

restore_dist_interfaces: True

2.1.19 sources

Specify the root image to install on to the target system. The URI also configures the method used to copy the imageto the target system.

sources:

source URI may be one of:

• dd-: Use dd command to write image to target.

• cp://: Use rsync command to copy source directory to target.

• file://: Use tar command to extract source to target.

• squashfs://: Mount squashfs image and copy contents to target.

• http[s]://: Use wget | tar commands to extract source to target.

• fsimage:// mount filesystem image and copy contents to target. Local file or url are supported. Filesystem canbe any filesystem type mountable by the running kernel.

• fsimage-layered:// mount layered filesystem image and copy contents to target. A fsimage-layered installsource is a string representing one or more mountable images from a single local or remote directory. The stringis dot-separated where each value between the dots represents a particular image and the location of the namewithin the string encodes the order in which it is to be mounted. The resulting list of images are downloaded (ifneeded) then mounted and overlayed into a single directory which is used as the source for installation.

Image Name Pattern

[[.]. . . ].

Example:



10-base.imgminimal.imgminimal.standard.live.squashfshttp://example.io/standard.squashfs

Layer Dependencies

Layers are parts of the name seperated by dots. Any layer in the name will be included as a dependency. The fileextension pattern is used to find related layers.

Examples:

Base use case:

/imagesmain.squashfsmain.upper.squashfsmain.upper.debug.squashfs

source=’fsimage-layered://images/main.squashfs’ -> images=’/images/main.squashfs’source=’fsimage-layered://images/main.upper.squashfs’ -> images=’/images/main.upper.squashfs,/images/main.squashfs’ source=’fsimage-layered://images/main.upper.debug.squashfs’ -> im-ages=’/images/main.upper.debug.squashfs, /images/main.upper.squashfs, /images/main.squashfs’

Multiple extensions:

/imagesmain.squashfsmain.imgmain.upper.squashfsmain.upper.imgmain.upper.debug.squashfs

source=’fsimage-layered://images/main.upper.squashfs’ -> images=’/images/main.upper.squashfs,/images/main.squashfs’ source=’fsimage-layered://images/main.upper.img’ -> im-ages=’/images/main.upper.img, /images/main.img’

Missing intermediary layer:

/imagesmain.squashfsmain.upper.debug.squashfs

If there is a missing image in the path to a leaf, an error will be raised

source=’fsimage-layered://images/main.squashfs’ -> images=’/images/main.squashfs’ source=’fsimage-layered://images/main.upper.debug.squashfs’ -> Raised Error’

Remote Layers:

http://example.io/base.extended.debug.squashfs

The URI passed to fsimage-layered may be on a remote system. Curtin will parse the URI and then downloadeach layer from the remote system. This results in Curtin downloading the following URLs:

- http://example.io/base.squashfshttp://example.io/base.extended.squashfshttp://example.io/base.extended.debug.squashfs

Example Cloud-image:



sources:- https://cloud-images.ubuntu.com/xenial/current/xenial-server-cloudimg-amd64-root.

→˓tar.gz

Example Custom DD image:

sources:- dd-img: https://localhost/raw_images/centos-6-3.img

Example Copy from booted environment:

sources:- cp:///

Example squashfs from NFS mount::

sources:

• squashfs:///media/filesystem.squashfs

Example Copy from local tarball:

sources:- file:///tmp/root.tar.gz

2.1.20 stages

Curtin installation executes in stages. At each stage, Curtin will look for a list of commands to run at each stage byreading in from the Curtin config _commands which is a dictionary and each key contains a list ofcommands to run. Users may override the stages value to control what curtin stages execute. During each stage, thecommands are executed in C Locale sort order. Users should name keys in a NN-XXX format where NN is a two-digitnumber to exercise control over execution order.

The following stages are defined in Curtin and run by default.

• early: Preparing for Installation

This stage runs before any actions are taken for installation. By default this stage does nothing.

• partitioning: Select and partition disks for installation

This stage runs curtin block-meta simple by default.

• network: Probe and configure networking

This stage runs curtin net-meta auto by default.

• extract: Writing install sources to disk

This stage runs curtin extract by default.

• extract: Writing install sources to disk

This stage runs curtin extract by default.

• curthooks: Configuring installed system

This stage runs curtin curthooks by default.

• hooks: Finalizing installation

This stage runs curtin hook by default.



• late: Executing late commands

This stage runs after Curtin has completed the installation. By default this stage does nothing.

Example Custom Stages:

# Skip the whole install and just run `mystage`stages: ['early', 'late', 'mystage']mystage_commands:

00-cmd: ['/usr/bin/foo']

Example Early and Late commands:

early_commands:99-cmd: ['echo', 'I ran last']00-cmd: ['echo', 'I ran first']

late_commands:50-cmd: ['curtin', 'in-target' '--', 'touch', '/etc/disable_overlayroot']

2.1.21 swap

Curtin can configure a swapfile on the filesystem in the target system. Size settings can be integer or string values withsuffix. Curtin supports the following suffixes which multiply the value.

• B: 1

• K[B]: 1


(continued from previous page)

swap:filename: btrfs_swapfile.imgsize: 1GBforce: true

2.1.22 system_upgrade

Control if Curtin runs dist-upgrade in target after install. Defaults to False.

enabled:

Example:

system_upgrade:enabled: False

2.1.23 write_files

Curtin supports writing out arbitrary data to a file. write_files accepts a dictionary of entries formatted as follows:

path:

Specify the name and location of where to write the content.

permissions:

Specify the permissions mode as an integer or string of numbers.

content:

Specify the content.

Example:

write_files:f1:path: /file1content: !!binary |

f0VMRgIBAQAAAAAAAAAAAAIAPgABAAAAwARAAAAAAABAAAAAAAAAAJAVAAAAAAAf2: {path: /file2, content: "foobar", permissions: '0666'}


CHAPTER 3

APT Source

This part of curtin is meant to allow influencing the apt behaviour and configuration.

By default - if no apt config is provided - it does nothing. That keeps behavior compatible on upgrades.

The feature has an optional target argument which - by default - is used to modify the environment that curtin currentlyinstalls (@TARGET_MOUNT_POINT).

3.1 Features

• Add PGP keys to the APT trusted keyring

– add via short keyid

– add via long key fingerprint

– specify a custom keyserver to pull from

– add raw keys (which makes you independent of keyservers)

• Influence global apt configuration

– adding ppa’s

– replacing mirror, security mirror and release in sources.list

– able to provide a fully custom template for sources.list

– add arbitrary apt.conf settings

– provide debconf configurations

– disabling suites (=pockets)

– per architecture mirror definition

21


3.2 Configuration

The general configuration of the apt feature is under an element called apt.

This can have various “global” subelements as listed in the examples below. The file apt-source.yaml holdsmore examples.

These global configurations are valid throughput all of the apt feature. So for exmaple a global specification of aprimary mirror will apply to all rendered sources entries.

Then there is a section sources which can hold any number of source subelements itself. The key is the filenameand will be prepended by /etc/apt/sources.list.d/ if it doesn’t start with a /. There are certain cases - where no contentis written into a source.list file where the filename will be ignored - yet it can still be used as index for merging.

The values inside the entries consist of the following optional entries

• source: a sources.list entry (some variable replacements apply)

• keyid: providing a key to import via shortid or fingerprint

• key: providing a raw PGP key

• keyserver: specify an alternate keyserver to pull keys from that were specified by keyid

The section “sources” is is a dictionary (unlike most block/net configs which are lists). This format allows mergingbetween multiple input files than a list like

sources:s1: {'key': 'key1', 'source': 'source1'}

sources:s2: {'key': 'key2'}s1: {'keyserver': 'foo'}

This would be merged intos1: {'key': 'key1', 'source': 'source1', keyserver: 'foo'}s2: {'key': 'key2'}

Here is just one of the most common examples for this feature: install with curtin in an isolated environment (derivedrepository):

For that we need to: * insert the PGP key of the local repository to be trusted

• since you are locked down you can’t pull from keyserver.ubuntu.com

• if you have an internal keyserver you could pull from there, but let us assume you don’t even have that; so youhave to provide the raw key

• in the example I’ll use the key of the “Ubuntu CD Image Automatic Signing Key” which makes no sense as itis in the trusted keyring anyway, but it is a good example. (Also the key is shortened to stay readable)

-----BEGIN PGP PUBLIC KEY BLOCK-----Version: GnuPG v1mQGiBEFEnz8RBAC7LstGsKD7McXZgd58oN68KquARLBl6rjA2vdhwl77KkPPOr3ORwIbDAAKCRBAl26vQ30FtdxYAJsFjU+xbex7gevyGQ2/mhqidES4MwCggqQyo+w1Twx6DKLF+3rF5nf1F3Q==PBAe-----END PGP PUBLIC KEY BLOCK-----

• replace the mirrors used to some mirrors available inside the isolated environment for apt to pull repository datafrom.

22 Chapter 3. APT Source


– lets consider we have a local mirror at mymirror.local but otherwise following the usual paths

– make an example with a partial mirror that doesn’t mirror the backports suite, so backports have to bedisabled

That would be specified as

apt:primary:- arches [default]

uri: http://mymirror.local/ubuntu/disable_suites: [backports]sources:localrepokey:

key: | # full key as block-----BEGIN PGP PUBLIC KEY BLOCK-----Version: GnuPG v1

mQGiBEFEnz8RBAC7LstGsKD7McXZgd58oN68KquARLBl6rjA2vdhwl77KkPPOr3ORwIbDAAKCRBAl26vQ30FtdxYAJsFjU+xbex7gevyGQ2/mhqidES4MwCggqQyo+w1Twx6DKLF+3rF5nf1F3Q==PBAe-----END PGP PUBLIC KEY BLOCK-----

The file examples/apt-source.yaml holds various further examples that can be configured with this feature.

3.3 Common snippets

This is a collection of additional ideas people can use the feature for customizing their to-be-installed system.

• enable proposed on installing

apt:sources:proposed.list:

source: |deb $MIRROR $RELEASE-proposed main restricted universe multiverse

• Make debug symbols available

apt:sources:ddebs.list:

source: |deb http://ddebs.ubuntu.com $RELEASE main restricted universe multiversedeb http://ddebs.ubuntu.com $RELEASE-updates main restricted universe

→˓multiversedeb http://ddebs.ubuntu.com $RELEASE-security main restricted universe

→˓multiversedeb http://ddebs.ubuntu.com $RELEASE-proposed main restricted universe

→˓multiverse

3.3. Common snippets 23


3.4 Timing

The feature is implemented at the stage of curthooks_commands, which runs just after curtin has extracted the imageto the target. Additionally it can be ran as standalong command “curtin -v –config apt-config”.

This will pick up the target from the environment variable that is set by curtin, if you want to use it to a different targetor outside of usual curtin handling you can add --target to it to overwrite the target path. This targetshould have at least a minimal system with apt, apt-add-repository and dpkg being installed for the functionality towork.

3.5 Dependencies

Cloud-init might need to resolve dependencies and install packages in the ephemeral environment to run curtin. There-fore it is recommended to not only provide an apt configuration to curtin for the target, but also one to the installenvironment via cloud-init.

3.6 apt preserve_sources_list setting

cloud-init and curtin treat the preserve_sources_list setting slightly differently, and thus this setting deservesits own section.

3.6.1 Interpretation / Meaning

curtin reads preserve_sources_list to indicate whether or not it should update the target systems’ /etc/apt/sources.list. This includes replacing the mirrors used (apt/primary. . . ).

cloud-init reads preserve_sources_list to indicate whether or not it should render /etc/apt/sources.list from its built-in template.

3.6.2 defaults

Just for reference, the preserve_sources_list defaults in curtin and cloud-init are:

• curtin: true By default curtin will not modify /etc/apt/sources.list in the installed OS. It is assumedthat this file is intentionally as it is.

• cloud-init: false

• cloud-init in ephemeral environment: false

• cloud-init system installed by curtin: true (curtin writes this to a file /etc/cloud/cloud.cfg.d/curtin-preserve-sources.cfg in the target). It does this because we have already written thesources.list that is desired in the installer. We do not want cloud-init to overwrite it when it boots.

3.6.3 preserve_sources_list in MAAS

Curtin and cloud-init use the same apt configuration language. MAAS provides apt config in three different scenarios.

1. To cloud-init in ephemeral environment (rescue, install or commissioning) Here MAAS should not send avalue. If it wants to be explicit it should send preserve_sources_list: false.



2. To curtin in curtin config MAAS should send ‘‘preserve_sources_list: false‘‘. curtin will correctly readand update mirrors in official Ubuntu images, so setting this to ‘false’ is correct. In some cases for customimages, the user might want to be able to have their /etc/apt/sources.list left untouched entirely. In suchcases they may want to override this value.

3. To cloud-init via curtin config in debconf_selections. MAAS should not send a value. Curtin will handletelling cloud-init to not update /etc/apt/sources.list. MAAS does not need to do this.

4. To installed system via vendor-data or user-data. MAAS should not send a value. MAAS does not cur-rently send a value. The user could send one in user-data, but then if they did presumably they did that fora reason.

3.6.4 Legacy format

Versions of cloud-init in 14.04 and older only support:

apt_preserve_sources_list: VALUE

Versions of cloud-init present 16.04+ read the “new” style apt configuration, but support the old style configurationalso. The new style configuration is:

apt:preserve_sources_list: VALUE

Note: If versions of cloud-init that support the new style config receive conflicting values in old style and new style,cloud-init will raise exception and exit failure. It simplly doesn’t know what behavior is desired.

3.6. apt preserve_sources_list setting 25

CHAPTER 4

Networking

Curtin supports a user-configurable networking configuration format. This format lets users (including via MAAS)to customize their machines’ networking interfaces by assigning subnet configuration, virtual device creation (bonds,bridges, vlans) routes and DNS configuration.

Curtin accepts a YAML input under the top-level network key to indicate that a user would like to specify a customnetworking configuration. Required elements of a network configuration are config and version. Currently curtinonly supports network config version=1.

network:version: 1config: []

4.1 Configuration Types

Within the network config portion, users include a list of configuration types. The current list of support typevalues are as follows:

• Physical (physical)

• Bond (bond)

• Bridge (bridge)

• VLAN (vlan)

• Nameserver (nameserver)

• Route (route)

Physical, Bond, Bridge and VLAN types may also include IP configuration under the key subnets.

• Subnet/IP (subnets)

27


4.1.1 Physical

The physical type configuration represents a “physical” network device, typically Ethernet-based. At least oneof of these entries is required for external network connectivity. Type physical requires only one key: name. Aphysical device may contain some or all of the following keys:

name:

A devices name must be less than 15 characters. Names exceeding the maximum will be truncated. This is a limitationof the Linux kernel network-device structure.

mac_address:

The MAC Address is a device unique identifier that most Ethernet-based network devices possess. Specifying a MACAddress is optional.

Note: Curtin will emit a udev rule to provide a persistent mapping between a device’s name and the mac_address.

mtu:

The MTU key represents a device’s Maximum Transmission Unit, the largest size packet or frame, specified in octets(eight-bit bytes), that can be sent in a packet- or frame-based network. Specifying mtu is optional.

Note: The possible supported values of a device’s MTU is not available at configuration time. It’s possible to specifya value too large or to small for a device and may be ignored by the device.

Physical Example:

network:version: 1config:# Simple network adapter- type: physical

name: interface0mac_address: 00:11:22:33:44:55

# Second nic with Jumbo frames- type: physical

name: jumbo0mac_address: aa:11:22:33:44:55mtu: 9000

# 10G pair- type: physical

name: gbe0mac_address: cd:11:22:33:44:00

- type: physicalname: gbe1mac_address: cd:11:22:33:44:02

4.1.2 Bond

A bond type will configure a Linux software Bond with one or more network devices. A bond type requires thefollowing keys:

name:

28 Chapter 4. Networking


A devices name must be less than 15 characters. Names exceeding the maximum will be truncated. This is a limitationof the Linux kernel network-device structure.

mac_address:

When specifying MAC Address on a bond this value will be assigned to the bond device and may be different than theMAC address of any of the underlying bond interfaces. Specifying a MAC Address is optional. If mac_address isnot present, then the bond will use one of the MAC Address values from one of the bond interfaces.

bond_interfaces:

The bond_interfaces key accepts a list of network device name values from the configuration. This list may beempty.

params:

The params key in a bond holds a dictionary of bonding parameters. This dictionary may be empty. For more detailson what the various bonding parameters mean please read the Linux Kernel Bonding.txt.

Valid params keys are:

• active_slave: Set bond attribute

• ad_actor_key: Set bond attribute

• ad_actor_sys_prio: Set bond attribute

• ad_actor_system: Set bond attribute

• ad_aggregator: Set bond attribute

• ad_num_ports: Set bond attribute

• ad_partner_key: Set bond attribute

• ad_partner_mac: Set bond attribute

• ad_select: Set bond attribute

• ad_user_port_key: Set bond attribute

• all_slaves_active: Set bond attribute

• arp_all_targets: Set bond attribute

• arp_interval: Set bond attribute

• arp_ip_target: Set bond attribute

• arp_validate: Set bond attribute

• downdelay: Set bond attribute

• fail_over_mac: Set bond attribute

• lacp_rate: Set bond attribute

• lp_interval: Set bond attribute

• miimon: Set bond attribute

• mii_status: Set bond attribute

• min_links: Set bond attribute

• mode: Set bond attribute

• num_grat_arp: Set bond attribute

• num_unsol_na: Set bond attribute

4.1. Configuration Types 29


• packets_per_slave: Set bond attribute

• primary: Set bond attribute

• primary_reselect: Set bond attribute

• queue_id: Set bond attribute

• resend_igmp: Set bond attribute

• slaves: Set bond attribute

• tlb_dynamic_lb: Set bond attribute

• updelay: Set bond attribute

• use_carrier: Set bond attribute

• xmit_hash_policy: Set bond attribute

Bond Example:



# 10G pair- type: physical



- type: bondname: bond0bond_interfaces:

- gbe0- gbe1

params:bond-mode: active-backup

4.1.3 Bridge

Type bridge requires the following keys:

• name: Set the name of the bridge.

• bridge_interfaces: Specify the ports of a bridge via their name. This list may be empty.

• params: A list of bridge params. For more details, please read the bridge-utils-interfaces manpage.

Valid keys are:

• bridge_ageing: Set the bridge’s ageing value.

• bridge_bridgeprio: Set the bridge device network priority.

• bridge_fd: Set the bridge’s forward delay.

• bridge_hello: Set the bridge’s hello value.



• bridge_hw: Set the bridge’s MAC address.

• bridge_maxage: Set the bridge’s maxage value.

• bridge_maxwait: Set how long network scripts should wait for the bridge to be up.

• bridge_pathcost: Set the cost of a specific port on the bridge.

• bridge_portprio: Set the priority of a specific port on the bridge.

• bridge_ports: List of devices that are part of the bridge.

• bridge_stp: Set spanning tree protocol on or off.

• bridge_waitport: Set amount of time in seconds to wait on specific ports to become available.

Bridge Example:



# Second nic with Jumbo frames- type: physical

name: jumbo0mac_address: aa:11:22:33:44:55mtu: 9000

- type: bridgename: br0bridge_interfaces:

- jumbo0params:

bridge_ageing: 250bridge_bridgeprio: 22bridge_fd: 1

bridge_hello: 1bridge_maxage: 10bridge_maxwait: 0bridge_pathcost:- jumbo0 75

bridge_pathprio:- jumbo0 28

bridge_stp: 'off'bridge_maxwait:- jumbo0 0

4.1.4 VLAN

Type vlan requires the following keys:

• name: Set the name of the VLAN

• vlan_link: Specify the underlying link via its name.

• vlan_id: Specify the VLAN numeric id.

VLAN Example:



network:version: 1config:# Physical interfaces.- type: physical

name: eth0mac_address: "c0:d6:9f:2c:e8:80"

# VLAN interface.- type: vlan

name: eth0.101vlan_link: eth0vlan_id: 101mtu: 1500

4.1.5 Nameserver

Users can specify a nameserver type. Nameserver dictionaries include the following keys:

• address: List of IPv4 or IPv6 address of nameservers.

• search: List of of hostnames to include in the resolv.conf search path.

Nameserver Example:

network:version: 1config:- type: physical

name: interface0mac_address: 00:11:22:33:44:55subnets:

- type: staticaddress: 192.168.23.14/27gateway: 192.168.23.1

- type: nameserver:address:

- 192.168.23.2- 8.8.8.8

search:- exemplary

4.1.6 Route

Users can include static routing information as well. A route dictionary has the following keys:

• destination: IPv4 network address with CIDR netmask notation.

• gateway: IPv4 gateway address with CIDR netmask notation.

• metric: Integer which sets the network metric value for this route.

Route Example:

network:version: 1config:

(continues on next page)




- type: physicalname: interface0mac_address: 00:11:22:33:44:55subnets:

- type: staticaddress: 192.168.23.14/24gateway: 192.168.23.1

- type: routedestination: 192.168.24.0/24gateway: 192.168.24.1metric: 3

4.1.7 Subnet/IP

For any network device (one of the Config Types) users can define a list of subnets which contain ip configu-ration dictionaries. Multiple subnet entries will create interface alias allowing a single interface to use different ipconfigurations.

Valid keys for for subnets include the following:

• type: Specify the subnet type.

• control: Specify manual, auto or hotplug. Indicates how the interface will be handled during boot.

• address: IPv4 or IPv6 address. It may include CIDR netmask notation.

• netmask: IPv4 subnet mask in dotted format or CIDR notation.

• gateway: IPv4 address of the default gateway for this subnet.

• dns_nameserver: Specify a list of IPv4 dns server IPs to end up in resolv.conf.

• dns_search: Specify a list of search paths to be included in resolv.conf.

Subnet types are one of the following:

• dhcp4: Configure this interface with IPv4 dhcp.

• dhcp: Alias for dhcp4

• dhcp6: Configure this interface with IPv6 dhcp.

• static: Configure this interface with a static IPv4.

• static6: Configure this interface with a static IPv6 .

When making use of dhcp types, no additional configuration is needed in the subnet dictionary.

Subnet DHCP Example:



- type: dhcp

Subnet Static Example:





- type: staticaddress: 192.168.23.14/27gateway: 192.168.23.1dns_nameservers:

- 192.168.23.2- 8.8.8.8

dns_search:- exemplary.maas

The following will result in an interface0 using DHCP and interface0:1 using the static subnet configuration.

Multiple subnet Example:



- type: dhcp- type: staticaddress: 192.168.23.14/27gateway: 192.168.23.1dns_nameservers:

- 192.168.23.2- 8.8.8.8

dns_search:- exemplary

4.2 Multi-layered configurations

Complex networking sometimes uses layers of configuration. The syntax allows users to build those layers one at atime. All of the virtual network devices supported allow specifying an underlying device by their name value.

Bonded VLAN Example:

network:version: 1config:# 10G pair- type: physical



# Bond.





- type: bondname: bond0bond_interfaces:

- gbe0- gbe1

params:bond-mode: 802.3adbond-lacp-rate: fast

# A Bond VLAN.- type: vlan

name: bond0.200vlan_link: bond0vlan_id: 200subnets:

- type: dhcp4

4.3 More Examples

Some more examples to explore the various options available.

Multiple VLAN example:

network:version: 1config:- id: eth0mac_address: d4:be:d9:a8:49:13mtu: 1500name: eth0subnets:- address: 10.245.168.16/21

dns_nameservers:- 10.245.168.2gateway: 10.245.168.1type: static

type: physical- id: eth1mac_address: d4:be:d9:a8:49:15mtu: 1500name: eth1subnets:- address: 10.245.188.2/24

dns_nameservers: []type: static

type: physical- id: eth1.2667mtu: 1500name: eth1.2667subnets:- address: 10.245.184.2/24


type: vlanvlan_id: 2667


4.3. More Examples 35



vlan_link: eth1- id: eth1.2668mtu: 1500name: eth1.2668subnets:- address: 10.245.185.1/24


type: vlanvlan_id: 2668vlan_link: eth1

- id: eth1.2669mtu: 1500name: eth1.2669subnets:- address: 10.245.186.1/24



- id: eth1.2670mtu: 1500name: eth1.2670subnets:- address: 10.245.187.2/24



- address: 10.245.168.2search:- dellstacktype: nameserver


CHAPTER 5

Storage

Curtin supports a user-configurable storage layout. This format lets users (including via MAAS) to customize theirmachines’ storage configuration by creating partitions, RAIDs, LVMs, formatting with file systems and setting mountpoints.

Custom storage configuration is handled by the block-meta custom command in curtin. Partitioning layout isread as a list of in-order modifications to make to achieve the desired configuration. The top level configuration keycontaining this configuration is storage. This key should contain a dictionary with at least a version number andthe configuration list. The current config specification is version: 1.

Config Example:

storage:version: 1config:- id: sda

type: diskptable: gptserial: QM00002model: QEMU_HARDDISK

5.1 Configuration Types

Each entry in the config list is a dictionary with several keys which vary between commands. The two dictionary keysthat every entry in the list needs to have are id: and type: .

An entry’s id allows other entries in the config to refer to a specific entry. It can be any string other than one with aspecial meaning in yaml, such as true or none.

An entry’s type tells curtin how to handle a particular entry. Available commands include:

• Dasd Command (dasd)

• Disk Command (disk)

37


• Partition Command (partition)

• Format Command (format)

• Mount Command (mount)

• LVM_VolGroup Command (lvm_volgroup)

• LVM_Partition Command (lvm_partition)

• DM_Crypt Command (dm_crypt)

• RAID Command (raid)

• Bcache Command (bcache)

• Zpool Command (zpool) Experimental

• ZFS Command (zfs)) Experimental

5.1.1 Dasd Command

The dasd command sets up an ECKD s390x system DASD device for use by curtin. FBA DASD devices do notrequire this low level set up. ECKD DASD drives can also be passed via virtio to KVM virtual machines and in thiscase this set up must be done on the host prior to starting the virtual machine.

DASD devices require several parameters to configure the low-level structure of the block device. Curtin will examinethe configuration and determine if the specified DASD matches the configuration. If the device does not match theconfiguration Curtin will perform a format of the device to achieve the required configuration. Once a DASD devicehas been formatted it may be used like regular Linux block devices and can be partitioned (with limitations) withCurtin’s disk command. The dasd command may contain the following keys:

device_id:

The device_id value is used to select a specific DASD device.

blocksize: 512, 1024, 2048, 4096

Specify blocksize to be used. blocksize must be a positive integer and always be a power of two. The defaultblocksize is 4096 bytes.

Note: The net capacity of an ECKD™ DASD decreases for smaller block sizes. For example, a DASD formattedwith a block size of 512 byte has only half of the net capacity of the same DASD formatted with a block size of 4096byte.

mode: quick, full, expand

Specify the mode to be used to format the device. The default mode is full which will format the entire disk.

Using quick mode will format the first two tracks and write label and partition information. Only use this option ifyou are sure that the target DASD has already been formatted in a disk_layout and blocksize desired.

The expand mode will format all unformatted tracks at the end of the target DASD. This mode assumes that tracksat the beginning of the DASD volume have already been correctly formatted.

label:

The label value sets the volume serial number (volser) that will be written to the specified DASD after formatting.If no label value is provided one will be generated. The value provided is interpreted as ASCII string and convertedto uppercase and then to EBCDIC.

38 Chapter 5. Storage


Valid labels are 6 characters long and can alphanumeric values, $, #, @, and %. Shorter values will be padded withtrailing spaces.

These label values are reserved and cannot be used:

MIGRAT, SCRTCH, PRIVAT, or Lnnnnn (L with five numbers);

disk_layout: cdl, ldl

The default disk_layout value is cdl, the compaible disk layout which allows for up to 3 partitions and a VTOC.The ldl, Linux layout has only one partition.

Config Example:

- id: dasd_roottype: dasddevice_id: 0.0.1520blocksize: 4096disk_layout: cdllabel: 0X1520mode: full

- id: disk0type: diskptable: vtocserial: 0X1520name: root_diskwipe: superblock

5.1.2 Disk Command

The disk command sets up disks for use by curtin. It can wipe the disks, create partition tables, or just verify that thedisks exist with an existing partition table. A disk command may contain all or some of the following keys:

ptable: msdos, gpt, vtoc

If the ptable key is present and a curtin will create an empty partition table of that type on the disk. On almostall drives, curtin supports msdos and gpt partition tables; ECKD DASD drives on s390x mainframes can only use the“vtoc” partition table.

serial:

In order to uniquely identify a disk on the system its serial number should be specified. This ensures that even ifadditional storage devices are added to the system during installation, or udev rules cause the path to a disk to changecurtin will still be able to correctly identify the disk it should be operating on using /dev/disk/by-id.

This is the preferred way to identify a disk and should be used in all production environments as it is less likely topoint to an incorrect device.

path:


• password: Password to authenticate with, if needed, for iSCSI initiator authentication. Only CHAP authenti-cation is supported at this time.

• iuser: User to authenticate with, if needed, for iSCSI target authentication. Only CHAP authentication issupported at this time.

• ipassword: Password to authenticate with, if needed, for iSCSI target authentication. Only CHAP authenti-cation is supported at this time.

Note: Curtin will treat it as an error if the user and password are not both specified for initiator and target authentica-tion.

• host: iSCSI server hosting the specified target. It can be a hostname, IPv4 or IPv6 address. If specified as anIPv6 address, it must be specified as [address].

• proto: Specifies the protocol used for iSCSI. Currently only 6, or TCP, is supported and any other value isignored. If not specified, 6 is assumed.

• port: Specifies the port the iSCSI server is listening on. If not specified, 3260 is assumed.

• lun: Specifies the LUN of the iSCSI target to connect to. If not specified, 0 is assumed.

• targetname: Specifies the iSCSI target to connect to, by its name on the iSCSI server.

Note: Curtin will treat it as an error if the host and targetname are not specified.

Any iSCSI disks specified will be configured to login at boot in the target.

model:

This can specify the manufacturer or model of the disk. It is not currently used by curtin, but can be useful for a humanreading a config file. Future versions of curtin may make use of this information.

wipe: superblock, superblock-recursive, pvremove, zero, random

If wipe is specified, the disk contents will be destroyed. In the case that a disk is a part of virtual block device, likebcache, RAID array, or LVM, then curtin will attempt to tear down the virtual device to allow access to the disk forresetting the disk.

The most common option for clearing a disk is wipe: superblock. In some cases use of wipe:superblock-recursive is useful to ensure that embedded superblocks on a disk aren’t rediscovered duringprobing. For example, LVM, bcache and RAID on a partition would have metadata outside of the range of a su-perblock wipe of the start and end sections of the disk.

The wipe: zero option will write zeros to each sector of the disk. Depending on the size and speed of the disk; itmay take a long time to complete.

The wipe: random option will write pseudo-random data from /dev/urandom Depending on the size and speedof the disk; it may take a long time to complete.

The wipe: pvremove option will execute the pvremove command to wipe the LVM metadata so that the deviceis no longer part of an LVM.

preserve: true, false

When the preserve key is present and set to true curtin will attempt reuse the existing storage device. Curtin willverify aspects of the device against the configuration provided. For example, when assessing whether curtin can use apreserved partition, curtin checks that the device exists, size of the partition matches the value in the config and checksif the same partition flag is set. The set of verification checks vary by device type. If curtin encounters a mismatch



between config and what is found on the device a RuntimeError will be raised with the expected and found values andhalt the installation. Currently curtin will verify the follow storage types:

• disk

• partition

• lvm_volgroup

• lvm_partition

• dm_crypt

• raid

• bcache

• format

One specific use-case of preserve: true is in conjunction with the wipe flag. This allows a device to reused,but have the content of the device to be removed.

name:

If the name key is present, curtin will create a udev rule that makes a symbolic link to the disk with the given namevalue. This makes it easy to find disks on an installed system. The links are created in /dev/disk/by-dname/. The udev rules will utilize two types of disk metadata to construct the link. For disks with serialand/or wwn values these will be used to ensure the name persists even if the contents of the disk change. For legacypurposes, curtin also emits a rule utilizing metadata on the disk contents, typically a partition UUID value, this alsopreserves these links for disks which lack persistent attributes such as a serial or wwn, typically found on virtualizedenvironments where such values are left unset.

A link to each partition on the disk will also be created at /dev/disk/by-dname/-part, soif name: maindisk is set, the disk will be at /dev/disk/by-dname/maindisk and the first partition on itwill be at /dev/disk/by-dname/maindisk-part1.

grub_device: true, false

If the grub_device key is present and set to true, then when post installation hooks are run grub will be installedonto this disk. In most situations it is not necessary to specify this value as curtin will detect and determine whichdevice to use as a boot disk. In cases where the boot device is on a special volume, such as a RAID array or a LVMLogical Volume, it may be necessary to specify the device that will hold the grub bootloader.

multipath:

If a disk is a path in a multipath device, it may be included in the configuration dictionary. Currently the value isinformational only. Curtin already detects whether disks are part of a multipath and selects one member path tooperate upon.

Config Example:

- id: disk0type: diskptable: gptserial: QM00002model: QEMU_HARDDISKname: maindiskwipe: superblock



5.1.3 Partition Command

The partition command creates a single partition on a disk. Curtin only needs to be told which disk to use and the sizeof the partition. Additional options are available.

number:

The partition number can be specified using number. However, numbers must be in order and some situations, suchas extended/logical partitions on msdos partition tables will require special numbering, so it maybe better to omit thepartition number. If the number key is not present, curtin will attempt determine the right number to use.

size:

The partition size can be specified with the size key. Sizes must be given with an appropriate SI unit, such as B, kB,MB, GB, TB, or using just the appropriate SI prefix, i.e. B, k, M, G, T. . .

Note: Curtin does not adjust size values. If you specific a size that exceeds the capacity of a device then installationwill fail.

device:

The device key refers to the id of a disk in the storage configuration. The disk entry must already be defined in thelist of commands to ensure that it has already been processed.


After the partition is added to the disk’s partition table, curtin can run a wipe command on the partition. The wipecommand values are the sames as for disks.

Note: Curtin will automatically wipe 1MB at the starting location of the partition prior to creating the partition toensure that other block layers or devices do not enable themselves and prevent accessing the partition.

flag: logical, extended, boot, bios_grub, swap, lvm, raid, home, prep

If the flag key is present, curtin will set the specified flag on the partition. Note that some flags only apply to msdospartition tables, and some only apply to gpt partition tables.

The logical/extended partition flags can be used to create logical partitions on a msdos table. An extended partitionshould be created containing all of the empty space on the drive, and logical partitions can be created within it. Aextended partition must already be present to create logical partitions. If the number flag is set for an extendedpartition it must be set to 4, and each logical partition should be numbered starting from 5.

On msdos partition tables, the boot flag sets the boot parameter to that partition. On gpt partition tables, the boot flagsets the esp flag on the partition.

If the host system for curtin has been booted using UEFI then curtin will install grub to the esp partition. If the systeminstallation media has been booted using an MBR, grub will be installed onto the disk’s MBR. However, on a diskwith a gpt partition table, there is not enough space after the MBR for grub to store its second stage core.img, so asmall un-formatted partition with the bios_grub flag is needed. This partition should be placed at the beginning of thedisk and should be 1MB in size. It should not contain a filesystem or be mounted anywhere on the system.


If the preserve flag is set to true, curtin will verify that the partition exists and that the size and flag match theconfiguration provided.

name:



If the name key is present, curtin will create a udev rule that makes a symbolic link to the partition with the givenname value. The links are created in /dev/disk/by-dname/.

For partitions, the udev rule created relies upon disk contents, in this case the partition entry UUID. This will remainin effect unless the underlying disk on which the partition resides has the partition table modified or wiped.

multipath:

If a partition is found on a multipath device, it may be included in the configuration dictionary. Currently the value isinformational only. Curtin already detects whether partitions are part of a multipath and selects one member path tooperate upon.

Config Example:

- id: disk0-part1type: partitionnumber: 1size: 8GBdevice: disk0flag: bootname: boot_partition

5.1.4 Format Command

The format command makes filesystems on a volume. The filesystem type and target volume can be specified, as wellas a few other options.

fstype: ext4, ext3, fat32, fat16, swap, xfs, zfsroot

Note: Filesystems support for ZFS on root is Experimental. Utilizing the the fstype: zfsroot will indicateto curtin that it should automatically inject the appropriate type: zpool and type: zfs command structuresbased on which target volume is specified in the format command. There may be only one zfsroot entry. The diskthat contains the zfsroot must be partitioned with a GPT partition table. Curtin will fail to install if these requirementsare not met.

The fstype key specifies what type of filesystem format curtin should use for this volume. Curtin knows aboutcommon Linux filesystems such as ext4/3 and fat filesystems and makes use of additional parameters and flags tooptimize the filesystem. If the fstype value is not known to curtin, that is not fatal. Curtin will check if mkfs. exists and if so, will use that tool to format the target volume.

For fat filesystems, the size of the fat table can be specified by entering fat64, fat32, fat16, or fat12 instead of justentering fat. If fat is used, then mkfs.fat will automatically determine the best size fat table to use, probably fat32.

If fstype: swap is set, curtin will create a swap partition on the target volume.

volume:

The volume key refers to the id of the target volume in the storage config. The target volume must already exist andbe accessible. Any type of target volume can be used as long as it has a block device that curtin can locate.

label:

The label key tells curtin to create a filesystem LABEL when formatting a volume. Note that not all filesystemtypes support names and that there are length limits for names. For fat filesystems, names are limited to 11 characters.For ext4/3 filesystems, names are limited to 16 characters.

If curtin does not know about the filesystem type it is using, then the label key will be ignored, because curtin willnot know the correct flags to set the label value in the filesystem metadata.



uuid:

If the uuid key is set and fstype is set to ext4 or ext3, then curtin will set the uuid of the new filesystem to thespecified value.


If the preserve key is set to true, curtin will not format the partition.

extra_options:

The extra_options key is a list of strings that is appended to the mkfs command used to create the filesystem.Use of this setting is dangerous. Some flags may cause an error during creation of a filesystem.

Config Example:

- id: disk0-part1-fs1type: formatfstype: ext4label: cloud-imagevolume: disk0-part1

- id: disk1-part1-fs1type: formatfstype: ext4label: osdata1uuid: ed51882e-8688-4cd8-97ca-1f2b8bbee458extra_options: ['-O', '^metadata_csum,^64bit']

- id: nvme1-part1-fs1type: formatfstype: ext4label: cacheset1extra_options:- -E- offset=1024,nodiscard

5.1.5 Mount Command

The mount command mounts the target filesystem and creates an entry for it in the newly installed system’s /etc/fstab. The path to the target mountpoint must be specified as well as the target filesystem.

path:

The path key tells curtin where the filesystem should be mounted on the target system. An entry in the target system’s/etc/fstab will be created for the target device which will mount it in the correct place once the installed systemboots.

If the device specified is formatted as swap space, then an entry will be added to the target system’s /etc/fstab tomake use of this swap space.

When entries are created in /etc/fstab, curtin will use the most reliable method available to identify each device.For regular partitions, curtin will use the UUID of the filesystem present on the partition. For special devices, such asRAID arrays, or LVM logical volumes, curtin will use their normal path in /dev.

device:

The device key refers to the id of a Format entry. One of device or spec must be present.



Note: If the specified device refers to an iSCSI device, the corresponding fstab entry will contain _netdev toindicate networking is required to mount this filesystem.

freq:

The freq key refers to the freq as defined in dump(8). Defaults to 0 if unspecified.

fstype:

fstype is only required if device is not present. It indicates the filesystem type and will be used for mountoperations and written to /etc/fstab

options:

The options key will replace the default options value of defaults.

Warning: The kernel and user-space utilities may differ between the install environment and the runtime environ-ment. Not all kernels and user-space combinations will support all options. Providing options for a mount pointwill have both of the following effects:

• curtin will mount the filesystems with the provided options during the installation.

• curtin will ensure the target OS uses the provided mount options by updating the target OS (/etc/fstab).

If either of the environments (install or target) do not have support for the provided options, the behavior is unde-fined.

passno:

The passno key refers to the fs_passno as defined in fsck(8). If unspecified, curtin will default to 1 or 0, de-pending on if that filesystem is considered to be a ‘nodev’ device per /proc/filesystems. Note that per systemd-fstab-generator(8), systemd interprets passno as a boolean.

spec:

The spec attribute defines the fsspec as defined in fstab(5). If spec is present with device, then mounts will bedone according to spec rather than determined via inspection of device. If spec is present without device thenfstype must be present.

Config Example:

- id: disk0-part1-fs1-mount0type: mountpath: /homedevice: disk0-part1-fs1options: 'noatime,errors=remount-ro'

Bind Mount

Below is an example of configuring a bind mount.

- id: bind1fstype: "none"options: "bind"path: "/var/lib"spec: "/my/bind-over-var-lib"type: mount

That would result in a fstab entry like:



/my/bind-over-var-lib /var/lib none bind 0 0

Tmpfs Mount

Below is an example of configuring a tmpfsbind mount.

- id: tmpfs1type: mountspec: "none"path: "/my/tmpfs"options: size=4194304fstype: "tmpfs"

That would result in a fstab entry like:

none /my/tmpfs tmpfs size=4194304 0 0

5.1.6 Lvm Volgroup Command

The lvm_volgroup command creates LVM Physical Volumes (PV) and connects them in a LVM Volume Group (vg).The command requires a name for the volgroup and a list of the devices that should be used as physical volumes.

name:

The name key specifies the name of the volume group. It anything can be used except words with special meaningsin YAML, such as true, or none.

devices: []

The devices key gives a list of devices to use as physical volumes. Each device is specified using the id of existingdevices in the storage config. Almost anything can be used as a device such as partitions, whole disks, RAID.


If the preserve option is True, curtin will verify that volume group specified by the name option is present andthat the physical volumes of the group match the devices specified in devices. There is no wipe option for volumegroups.

Config Example:

- id: volgroup1type: lvm_volgroupname: vg1devices:- disk0-part2- disk1

5.1.7 Lvm Partition Command

The lvm_partition command creates a lvm logical volume on the specified volgroup with the specified size. It alsoassigns it the specified name.

name:

The name key specifies the name of the Logical Volume (LV) to be created.

Curtin creates udev rules for Logical Volumes to give them consistently named symbolic links in the target sys-tem under /dev/disk/by-dname/. The naming scheme for Logical Volumes follows the pattern


name>-. For example a lvm_partition with name lv1 on a lvm_volgroupnamed vg1 would have the path /dev/disk/by-dname/vg1-lv1.

Note: dname values for contructed devices (such as lvm) only remain persistent as long as the device metadata doesnot change. If users modify the device such that device metadata is changed then the udev rule may no longer apply.

volgroup:

The volgroup key specifies the id of the Volume Group in which to create the logical volume. The volgroup mustalready have been created and must have enough free space on it to create the logical volume. The volgroup should bespecified using the id key of the volgroup in the storage config, not the name of the volgroup.

size:

The size key tells curtin what size to make the logical volume. The size can be entered in any format that can beprocessed by the lvm2 tools, so a number followed by a SI unit should work, i.e. B, kB, MB, GB, TB.

If the size key is omitted then all remaining space on the volgroup will be used for the logical volume.


If the preserve option is True, curtin will verify that specified lvm partition is part of the specified volume group.If size is specified curtin will verify the size matches the specified value.


If wipe option is set, and preserve is False, curtin will wipe the contents of the lvm partition. Curtin skips wipesettings if it creates the lvm partition.

Note: Curtin does not adjust size values. If you specific a size that exceeds the capacity of a device then installationwill fail.

Config Example:

- id: lvm_partition_1type: lvm_partitionname: lv1volgroup: volgroup1size: 10G

Combined Example:

- id: volgroup1type: lvm_volgroupname: vg1devices:- disk0-part2- disk1

- id: lvm_partition_1type: lvm_partitionname: lv1volgroup: volgroup1size: 10G



5.1.8 Dm-Crypt Command

The dm_crypt command creates encrypted volumes using cryptsetup. It requires a name for the encrypted volume,the volume to be encrypted and a key. In situations where the config is generated on a different system from wherecurtin is run there is not yet a good solution for securely conveying the key – you can set key but it appears in plaintext in the config, which might be intercepted by between the systems (and is by default copied to the target system).If the config is generated on the same system, you can use keyfile to supply the passphrase in file with appropriatepermissions.

volume:

The volume key gives the volume that is to be encrypted.

dm_name:

The name key specifies the name of the encrypted volume.

key:

The key key specifies the password of the encryption key. The target system will prompt for this password in orderto mount the disk.

keyfile:

The keyfile contains the password of the encryption key. The target system will prompt for this password in orderto mount the disk.

Exactly one of key and keyfile must be supplied.


If the preserve option is True, curtin will verify the dm-crypt device specified is composed of the device specifiedin volume.


If wipe option is set, and preserve is False, curtin will wipe the contents of the dm-crypt device. Curtin skips wipesettings if it creates the dm-crypt volume.

Note: Encrypted disks and partitions are tracked in /etc/crypttab and will be mounted at boot time.

Config Example:

- id: lvm_partition_1type: dm_cryptdm_name: cryptovolume: sdb1key: testkey

5.1.9 RAID Command

The RAID command configures Linux Software RAID using mdadm. It needs to be given a name for the md device, alist of volumes for to compose the md device, an optional list of devices to be used as spare volumes, and RAID level.

name:

The name key specifies the name of the md device.



Note: Curtin creates a udev rule to create a link to the md device in /dev/disk/by-dname/ using thespecified name. The dname symbolic link is only persistent as long as the raid metadata is not modifed or destroyed.

raidlevel: 0, 1, 5, 6, 10

The raidlevel key specifies the raid level of the array.

devices: []

The devices key specifies a list of the devices that will be used for the raid array. Each device must be referencedby id and the device must be previously defined in the storage configuration. Must not be empty.

Devices can either be full disks or partition.

spare_devices: []

The spare_devices key specifies a list of the devices that will be used for spares in the raid array. Each devicemust be referenced by id and the device must be previously defined in the storage configuration. May be empty.

ptable: msdos, gpt

To partition the array rather than mounting it directly, the ptable key must be present and a valid type of partitiontable, i.e. msdos or gpt.

metadata: default, 1.2, 1.1, 0.90, ddf, imsm

Specify the metadata (superblock) style to be used when creating the array. metadata defaults to the string “default”and is passed to mdadm. The version of mdadm used during the install will control the value here. Note that metadataversion 1.2 is the default in mdadm since release version 3.3 in 2013.


If the preserve option is True, curtin will verify the composition of the raid device. This includes array state, raidlevel, device md-uuid, composition of the array devices and spares and that all are present.


If wipe option is set to values other than ‘superblock’, curtin will wipe contents of the assembled raid device. Curtinskips ‘superblock‘ wipes as it already clears raid data on the members before assembling the array.

Config Example:

- id: raid_arraytype: raidname: md0raidlevel: 1metadata: 0.90devices:- sdb- sdc

spare_devices:- sdd

5.1.10 Bcache Command

The bcache command will configure a block-cache device using the Linux kernel bcache module. Bcache allows usersto use a typically small, but fast SSD or NVME device as a cache for larger, slower spinning disks.

The bcache command needs to be told which device to use hold the data and which device to use as its cache device.A cache device may be reused with multiple backing devices.



backing_device:

The backing_device key specifies the item in storage configuration to use as the backing device. This can be anydevice that would normally be used with a filesystem on it, such as a partition or a raid array.

cache_device:

The cache_device key specifies the item in the storage configuration to use as the cache device. This can bea partition or a whole disk. It should be on a ssd in most cases, as bcache is designed around the performancecharacteristics of a ssd.

cache_mode: writethrough, writeback, writearound, none

The cache_mode key specifies the mode in which bcache operates. The default mode is writethrough which ensuresdata hits the backing device before completing the operation. writeback mode will have higher performance butexposes dataloss if the cache device fails. writearound will avoid using the cache for large sequential writes; usefulfor not evicting smaller reads/writes from the cache. None effectively disables bcache.

name:

If the name key is present, curtin will create a link to the device at /dev/disk/by-dname/.

Note: dname values for contructed devices (such as bcache) only remain persistent as long as the device metadatadoes not change. If users modify the device such that device metadata is changed then the udev rule may no longerapply.


If the preserve option is True, curtin will verify the composition of the bcache device. This includes checkingthat backing device and cache device are enabled and bound correctly (backing device is cached by expected cachedevice). If cache-mode is specified, verify that the mode matches.


If wipe option is set, curtin will wipe the contents of the bcache device. If only cache device is specified, wipeoption is ignored.

Config Example:

- id: bcache0type: bcachename: cached_raidbacking_device: raid_arraycache_device: sdb

5.1.11 Zpool Command

ZFS Support is experimental.

The zpool command configures ZFS storage pools. A storage pool is a collection of devices that provides physicalstorage and data replication for ZFS datasets.

The zpool command needs to be provided with a list of physical devices, called vdevs.

Note: Curtin specifies zpool version=28 by default. This version is the most compatible with other ZFS implementa-tions. If newer ZFS features are required users may specify the version value in the pool_properties dictionary.Users may also run `zpool upgrade` to move to a new pool version. Some newer features may require migrationof data.


http://open-zfs.org/wiki/FAQ#Compatibility


For more information about versions and features consult:

http://open-zfs.org/wiki/

pool:

The pool key specifies the name of the ZFS storage pool. It will be used when constructing ZFS datasets.

vdevs: []

The vdevs key specifies a list of items in the storage configuration to use in building a ZFS storage pool. This canbe a partition or a whole disk. It is recommended that vdevs are disks which have a ‘serial’ attribute which allowsCurtin to build a /dev/disk/by-id path which is a persistent path, however, if not available Curtin will accept ‘path’attributes but warn that the zpool may be unstable due to missing by-id device path.

mountpoint:

The mountpoint key specifies where ZFS will mount the storage pool.

pool_properties: {}

The pool_properties key specifies a dictionary of key=value pairs which are passed to the ZFS storage poolconfiguration as properties of the pool. The default pool properties are:

• ashift: 12

• version: 28

fs_proper

curtin documentation · chapter 2 curtin conﬁguration curtin exposes a number of conﬁguration...

Documents