configuration.md

title	parent	nav_order
Configuration	API	2

Image Customizer configuration

The Image Customizer is configured using a YAML (or JSON) file.

Top-level

The top level type for the YAML file is the config type.

Operation ordering

1. If partitions were specified in the config, customize the disk partitions.

   Otherwise, if the resetPartitionsUuidsType value is specified, then the partitions' UUIDs are changed.

2. Override the /etc/resolv.conf file with the version from the host OS.

3. Update packages:

   1. Remove packages (removeLists, remove)

   2. Update base image packages (updateExistingPackages).

   3. Install packages (installLists, install)

   4. Update packages (updateLists, update)

4. Update hostname. (hostname)

5. Copy additional files. (additionalFiles)

6. Copy additional directories. (additionalDirs)

7. Add/update users. (users)

8. Enable/disable services. (services)

9. Configure kernel modules. (modules)

10. Write the /etc/image-customizer-release file.

11. Write the image history file.

12. If the bootloader resetType is set to hard-reset, then reset the boot-loader.

    If the bootloader resetType is not set, then append the extraCommandLine value to the existing grub.cfg file.

13. Update the SELinux mode. mode

14. If (overlays) are specified, then add the overlay driver and update the fstab file with the overlay mount information.

15. If a (verity) device is specified, then add the dm-verity dracut driver and update the grub config.

16. Regenerate the initramfs file (if needed).

17. Run (postCustomization) scripts.

18. Restore the /etc/resolv.conf file.

19. If SELinux is enabled, call setfiles.

20. Run finalize image scripts. (finalizeCustomization)

21. If --shrink-filesystems is specified, then shrink the file systems.

22. If a (verity) device is specified, then create the hash tree and update the grub config.

23. If the output format is set to iso, copy additional iso media files. (iso)

24. If --output-pxe-artifacts-dir is specified, then export the ISO image contents to the specified folder.

/etc/resolv.conf

The /etc/resolv.conf file is overridden during customization so that the package installation and customization scripts can have access to the network.

Near the end of customization, the /etc/resolv.conf file is restored to its original state.

However, if the /etc/resolv.conf did not exist in the base image and systemd-resolved service is enabled, then the /etc/resolv.conf file is symlinked to the /run/systemd/resolve/stub-resolv.conf file. (This would happen anyway during first-boot. But doing this during customization is useful for verity enabled images where the filesystem is readonly.)

If you want to explicitly set the /etc/resolv.conf file contents, you can do so within a finalizeCustomization script, since those scripts run after the /etc/resolv.conf is deleted.

Replacing packages

If you wish to replace a package with conflicting package, then you can remove the existing package using remove and then install the new package with install.

Example:

os:
  packages:
    remove:
    - kernel

    install:
    - kernel-uvm

Schema Overview

• config type
  • storage
    • bootType
    • disks (disk type)
      • partitionTableType
      • maxSize
      • partitions (partition type)
        • id
        • label
        • start
        • end
        • size
        • type
    • verity (verity type)
      • id
      • name
      • dataDeviceId
      • hashDeviceId
      • corruptionOption
    • filesystems (filesystem type)
      • deviceId
      • type
      • mountPoint (mountPoint type)
        • idType
        • options
        • path
    • resetPartitionsUuidsType
  • iso (iso type)
    • additionalFiles
      • additionalFile type
        • source
        • content
        • destination
        • permissions
    • kernelCommandLine (kernelCommandLine type)
      • extraCommandLine
  • pxe (pxe type)
    • isoImageBaseUrl
    • isoImageFileUrl
  • os (os type)
    • bootloader (bootloader type)
      • resetType
    • hostname
    • kernelCommandLine (kernelCommandLine type)
      • extraCommandLine
    • packages (packages type)
      • updateExistingPackages
      • installLists
      • install
      • removeLists
      • remove
      • updateLists
      • update
    • additionalFiles (additionalFile type)
      • source
      • content
      • destination
      • permissions
    • additionalDirs (dirConfig type)
      • source
      • destination
      • newDirPermissions
      • mergedDirPermissions
      • childFilePermissions
    • users (user type)
      • name
      • uid
      • password (password type)
        • type
        • value
      • passwordExpiresDays
      • sshPublicKeyPaths
      • primaryGroup
      • secondaryGroups
      • startupCommand
    • selinux (selinux type)
      • mode
    • services (selinux type)
      • enable
      • disable
    • modules (module type)
      • name
      • loadMode
      • options
    • overlays (overlay type)
    • uki (uki type)
      • kernels
    • imageHistory
  • scripts (scripts type)
    • postCustomization (script type)
      • path
      • content
      • interpreter
      • arguments
      • environmentVariables
      • name
    • finalizeCustomization (script type)
      • path
      • content
      • interpreter
      • arguments
      • environmentVariables
      • name
  • previewFeatures type