Skip to main content
The Azure Linux Image Customizer is a tool that takes an existing Azure Linux image and customizes it for a particular use case. It uses chroot and loopback devices to modify images offline without booting them, providing precise control over customizations.

​
Usage

imagecustomizer \
  --image-file <base-image> \
  --output-image-file <output-image> \
  --config-file <config.yaml> \
  --build-dir <build-dir> \
  [options]

​
Parameters

​
image-file
string
required
Path of the base Azure Linux image which the customization will be applied to
​
output-image-file
string
required
Path to write the customized image to
​
config-file
string
required
Path of the image customization config file (YAML format)
​
build-dir
string
required
Directory to run build out of
​
output-image-format
string
Format of output image. Supported: vhd, vhd-fixed, vhdx, qcow2, raw, iso
​
output-split-partitions-format
string
Format of partition files. Supported: raw, raw-zst
​
rpm-source
string
Path to a RPM repo config file or a directory containing RPMs (can be specified multiple times)
​
disable-base-image-rpm-repos
boolean
Disable the base image’s RPM repos as an RPM source
​
shrink-filesystems
boolean
Enable shrinking of filesystems to minimum size. Supports ext2, ext3, ext4 filesystem types. Requires --output-split-partitions-format.
​
output-pxe-artifacts-dir
string
Create a directory with customized image PXE booting artifacts. --output-image-format must be set to iso.
​
timestamp-file
string
File that stores timestamps for this program
​
log-file
string
Path to the log file
​
log-level
string
Log level (panic, fatal, error, warn, info, debug, trace)

​
How It Works

  1. Mount Image: Attaches the base image as a loopback device and mounts its filesystems
  2. Apply Customizations: Installs packages, modifies configurations, adds users, etc.
  3. Run Scripts: Executes custom scripts in chroot environment if specified
  4. Create Output: Generates the customized image in the specified format
  5. Optional Processing: Shrinks filesystems or creates PXE artifacts if requested

​
Customization Options

The YAML configuration file supports:

​
OS Customizations

  • Package Management: Install, remove, or update packages
  • Users and Groups: Create users, set passwords, configure SSH keys
  • Network: Configure hostname, network interfaces, DNS
  • Services: Enable or disable systemd services
  • Files: Add or modify files
  • Scripts: Run custom scripts during customization

​
Storage Customizations

  • Partitions: Modify partition layout
  • Filesystems: Resize or modify filesystems
  • Verity: Configure dm-verity for read-only partitions

​
Example Usage

​
Basic Package Installation

sudo imagecustomizer \
  --build-dir ./build \
  --image-file azurelinux-core.vhdx \
  --output-image-file ./custom.vhdx \
  --output-image-format vhdx \
  --config-file custom-config.yaml
custom-config.yaml: 
os:
  packagesInstall:
    - nginx
    - python3
  packagesRemove:
    - telnet

​
Advanced Customization

sudo imagecustomizer \
  --build-dir ./build \
  --image-file base.vhdx \
  --output-image-file ./production.vhdx \
  --output-image-format vhd-fixed \
  --config-file production-config.yaml \
  --rpm-source /path/to/custom/rpms
production-config.yaml: 
os:
  packagesInstall:
    - docker
    - kubernetes-kubeadm
  
  hostname: k8s-node-01
  
  users:
    - name: admin
      uid: 1000
      password:
        type: plain-text
        value: P@ssw0rd
      sshPublicKeys:
        - /path/to/id_rsa.pub
  
  services:
    - name: docker
      enabled: true
  
  additionalFiles:
    /etc/myapp/config.conf:
      source: ./configs/myapp.conf
      permissions: "0644"
  
  scripts:
    postCustomization:
      - path: ./scripts/setup.sh

​
ISO with PXE Artifacts

sudo imagecustomizer \
  --build-dir ./build \
  --image-file base.vhdx \
  --output-image-file ./installer.iso \
  --output-image-format iso \
  --output-pxe-artifacts-dir ./pxe \
  --config-file installer-config.yaml

​
Split Partitions with Shrinking

sudo imagecustomizer \
  --build-dir ./build \
  --image-file base.vhdx \
  --output-split-partitions-format raw-zst \
  --shrink-filesystems \
  --config-file minimal-config.yaml

​
Advantages of Chroot Approach

  • Lower Overhead: No need to boot and shutdown the OS
  • Precision: Direct file system modifications without running OS side effects
  • Fewer Requirements: SSH and other services don’t need to be pre-installed
  • Faster: No boot time or VM overhead

​
Limitations

  • Some tools don’t work properly in chroot (e.g., systemd operations, some network tools)
  • Cannot test runtime behavior during customization
  • Limited ability to initialize complex services (e.g., Kubernetes cluster initialization)

​
Notes

  • Requires root privileges for loopback device and chroot operations
  • Either --output-image-format or --output-split-partitions-format must be specified
  • The --shrink-filesystems flag is useful for creating minimal images but requires --output-split-partitions-format
  • Use --disable-base-image-rpm-repos when you want to use only specific RPM sources
  • Configuration file format is YAML, unlike imagegen which uses JSON

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us