General Configuration

Configuring an Elemental derivative

Elemental during installation, reset and upgrade (elemental install, elemental reset and elemental upgrade respectively) will read a configuration file in order to apply derivative customizations. The configuration files are sourced in precedence order and can be located in the following places:

/etc/os-release
<config-dir>/config.yaml
<config-dir>/config.d/*.yaml

By default <config-dir> is set to /etc/elemental however this can be changed to any custom path by using the --config-dir runtime flag.

Below you can find an example of the config file including most of the available options:

# DISCLAIMER: this document show most of all available options. Elemental
# uses defaults if any of this value is missing. Values shown here
# only represent an example and they should not be used as defaults.

# installation configuration for 'install' command
install:
  # target is the only value that has no default, it must be provided by
  # config, flags or env variables.
  target: /dev/sda

  # partitions setup
  # setting a partition size key to 0 means that the partition will take over the rest of the free space on the disk
  # after creating the rest of the partitions
  # by default the persistent partition has a value of 0
  # if you want any of the extra partitions to fill the rest of the space you will need to set the persistent partition
  # size to a different value, for example
  # partitions:
  #   persistent:
  #     size: 300

  # default partitions
  # only 'oem', 'recovery', 'state' and 'persistent' objects allowed
  # size in MiB
  partitions:
    oem:
      label: COS_OEM
      size: 60
      fs: ext4
    recovery:
      label: COS_RECOVERY
      size: 4096
      fs: ext4

  # extra partitions to create during install
  # only size, label and fs are used
  # if no fs is given the partition will be created but not formatted
  # This partitions are not automounted only created and formatted
  extra-partitions:
    - Name: myPartition
      size: 100
      fs: ext4
      label: EXTRA_PARTITION
    - Name: myOtherPartition
      size: 0
      fs: ext4
      label: EXTRA_PARTITION

  # no-format: true skips any disk partitioning and formatting
  # if set to true installation procedure will error out if expected
  # partitions are not already present within the disk.
  no-format: false

  # if no-format is used and elemental is running over an existing deployment
  # force cane be used to force installation.
  force: false

  # use this iso as installation media (overwrites 'system.uri' and 'recoverys-system.uri'
  # according to the ISO contents.
  iso: https://my.domain.org/some/powerful.iso

  # main OS image
  system: oci:some.registry.org/elemental/image:latest

  # recovery OS image
  recovery-system:
    fs: squashfs
    uri: oci:recovery/elemental

  snapshotter:
    type: loopdevice
    max-snaps: 4
    config:
      size: 0
      fs: ext2
      

  # extra cloud-init config file URI to include during the installation
  cloud-init: "https://some.cloud-init.org/my-config-file"

  # grub menu entry, this is the string that will be displayed
  grub-entry-name: Elemental

# configuration for the 'reset' command
reset:
  # if set to true it will format persistent partitions ('oem 'and 'persistent')
  reset-persistent: false
  reset-oem: false

  # OS image used to reset disk
  # size in MiB
  system:
    label: COS_ACTIVE
    size: 1024
    fs: ext2
    uri: docker:some.registry.org/cos/image:latest

  # filesystem label of the passive backup image
  passive.label: COS_PASSIVE

  # grub menu entry, this is the string that will be displayed
  grub-entry-name: Elemental

# configuration used for the 'upgrade' command
upgrade:
  # if set to true upgrade command will upgrade recovery system instead
  # of main active system
  recovery: false

  # image used to upgrade main OS
  # size in MiB
  system:
    uri: oci:system/elemental

  # image used to upgrade recovery OS
  # recovery images can be set to use squashfs
  recovery-system:
    fs: squashfs
    uri: oci:recovery/elemental

  # grub menu entry, this is the string that will be displayed
  grub-entry-name: Elemental

# configuration used for the 'mount' command
mount:
  sysroot: /sysroot # Path to mount system to
  write-fstab: true # Write fstab into sysroot/etc/fstab
  extra-volumes:
    - mountpoint: /run/elemental/efi
      device: PARTLABEL=efi
      options: ["ro", "defaults"]
    - mountpoint: /oem
      device: LABEL=COS_OEM
      options: ["defaults"]
  ephemeral:
    type: tmpfs # tmpfs|block
    device: /dev/sda6 # Block device used to store overlay. Used when type is set to block
    size: 25% # Size of tmpfs as percentag of system memory. Used when type is set to tmpfs
    paths:
      - /var
      - /etc
      - /srv
  persistent:
    mode: overlay # overlay|bind
    volume:
      mountpoint: /run/elemental/persistent
      device: PARTLABEL=persistent
      options: ["defaults"]
    paths:
      - /etc/systemd
      - /etc/ssh
      - /home
      - /opt
      - /root
      - /usr/libexec
      - /var/log

# use cosign to validate images from container registries
cosign: true
# cosign key to used for validation
cosign-key: myKey

# attempt a verify process
no-verify: false

# fail on cloud-init hooks errors
strict: false

# Additional paths to look for cloud-init files
cloud-init-paths:
- "/some/path"

# reboot/power off when done
reboot: false
poweroff: false

Complete source code: https://github.com/rancher/elemental-toolkit/blob/main/config.yaml.example

The system and recovery-system objects are an image specification. An image specification is defined by:

fs: defines the filesystem of the image. Currently only ext2 and squashfs should be used for images and squashfs is only supported for the recovery-system image.
label: defines the filesystem label. It is strongly recommended to use default labels as it is easy to fall into inconsistent states when changing labels as all changes should also be reflected in several other parts such as the bootloader configuration. This attribute has no effect for squashfs filesystems.
uri: defines the source of the image. The uri must include a valid scheme to identify the type of source. It supports oci, dir and file schemes.
size: defines the filesystem image size in MiB, it must be big enough to store the defined image source. This attribute has no effect for squashfs filesystems.

The partitions object lists partition specifications. A partition specifications is defined by:

fs: defines the filesystem of the partition. Currently only ext2, ext4 and xfs are supported being ext4 the default.
label: defines the label of the filesystem of the partition. It is strongly recommended to use default labels as it is easy to fall into inconsistent states when changing labels as all changes should also be reflected in several other parts such as the bootloader configuration.
size: defines the partition size in MiB. A zero size means use all available disk, obviously this only makes sense for the last partition, the persistent partition.
flags: is a list of strings, this is used as additional partition flags that are passed to parted (e.g. boot flag). Defaults should be just fine for most of the cases.

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Last modified August 31, 2023: More documentation work (#1819) (2360815df)