System Configuration - Azure Linux

The SystemConfigs section defines how each system on the image is configured, including boot settings, partition mounting, packages, users, and customization scripts.

System Configuration Structure

Name

string

required

Configuration name identifier

BootType

string

required

Boot type: efi or legacy

Hostname

string

System hostname

PartitionSettings

array

required

Array of partition mounting configurations

PackageLists

array

required

Array of package list file paths (relative to config file)

KernelOptions

object

required

Kernel package selection (required for non-rootfs images)

KernelCommandLine

object

Kernel command line parameters

Partition Settings

Partition settings define how partitions are mounted:

string

required

Partition ID (must match partition ID in Disks section)

MountPoint

string

required

Mount point path (e.g., /, /boot/efi)

MountOptions

string

Mount options (e.g., umask=0077)

MountIdentifier

string

How partition is identified in fstab: uuid, partuuid, partlabel. Default: partuuid

RdiffBaseImage

string

Base image path for rdiff differential images

OverlayBaseImage

string

Base image path for overlay differential images

Basic Partition Settings

"PartitionSettings": [
    {
        "ID": "boot",
        "MountPoint": "/boot/efi",
        "MountOptions": "umask=0077"
    },
    {
        "ID": "rootfs",
        "MountPoint": "/"
    }
]

Using Partition Labels

"Partitions": [
    {
        "ID": "rootfs",
        "Name": "my_rootfs",
        "Start": 9,
        "End": 0,
        "FsType": "ext4"
    }
]

"PartitionSettings": [
    {
        "ID": "rootfs",
        "MountPoint": "/",
        "MountIdentifier": "partlabel"
    }
]

partlabel cannot be used with mbr partition tables and requires the Name field in the partition definition.

Differential Images

For small, deterministic images, use rdiff:

{
    "ID": "boot",
    "MountPoint": "/boot/efi",
    "RdiffBaseImage": "../out/images/core-efi/core-efi-1.0.20200918.1751.ext4"
}

For large ext4-based images, use overlay:

{
    "ID": "rootfs",
    "MountPoint": "/",
    "OverlayBaseImage": "../out/images/core-efi/core-efi-rootfs-1.0.20200918.1751.ext4"
}

Kernel Configuration

Kernel Options

Specify which kernel packages to install:

default

string

required

Default kernel package name (e.g., kernel)

"KernelOptions": {
    "default": "kernel"
}

KernelOptions is mandatory for all non-rootfs image types. Do not include kernel packages in PackageLists.

Kernel Command Line

Configure kernel boot parameters:

ImaPolicy

array

IMA policies: tcb, appraise_tcb, secure_boot

EnableFIPS

boolean

Enable FIPS mode

SELinux

string

SELinux mode: enforcing, permissive, force_enforcing

SELinuxPolicy

string

SELinux policy package name. Default: selinux-policy

CGroup

string

CGroup version: version_one or version_two

ExtraCommandLine

string

Additional kernel parameters appended to command line

IMA and Custom Parameters

"KernelCommandLine": {
    "ImaPolicy": ["tcb"],
    "ExtraCommandLine": "console=ttyS0 my_param=value"
}

FIPS Mode

"KernelCommandLine": {
    "ExtraCommandLine": "fips=1"
}

SELinux

"KernelCommandLine": {
    "SELinux": "enforcing"
}

"KernelCommandLine": {
    "SELinux": "enforcing",
    "SELinuxPolicy": "my-selinux-policy"
}

CGroup v2

"KernelCommandLine": {
    "CGroup": "version_two"
}

Boot Configuration

EnableGrubMkconfig

boolean

Use grub2-mkconfig to generate boot config. Default: true

EnableSystemdFirstboot

boolean

Run systemd-firstboot on first boot. Default: false

IsKickStartBoot

boolean

Enable kickstart-style installation with preinstall scripts

Customization Scripts

Execute shell scripts at various points during image generation:

PreInstallScripts

array

Scripts run before partition creation (from installer context)

PostInstallScripts

array

Scripts run after package installation (from installed system)

FinalizeImageScripts

array

Scripts run before image finalization (from installed system)

Script Format

"PostInstallScripts": [
    {
        "Path": "scripts/configure-system.sh"
    },
    {
        "Path": "scripts/setup-network.sh",
        "Args": "--interface eth0 --dhcp"
    }
]

Script execution order: PreInstall → Create Partitions → Install Packages → PostInstall → Configure Bootloader → Finalize

PreInstall Scripts

Run before installation begins (from installer context):

"IsKickStartBoot": true,
"PreInstallScripts": [
    {
        "Path": "scripts/configure-partitions.sh"
    }
]

PreInstall scripts must set IsKickStartBoot to true and should create partition configuration at /tmp/part-include.

Additional Files

Copy files into the image:

AdditionalFiles

object

Map of source paths to destination paths (or FileConfig objects)

Simple File Copy

"AdditionalFiles": {
    "../../out/tools/imager": "/installer/imager",
    "configs/my-config.conf": "/etc/myapp/config.conf"
}

Multiple Destinations and Permissions

"AdditionalFiles": {
    "additionalconfigs": [
        "/etc/my/config.conf",
        {
            "Path": "/etc/yours/config.conf",
            "Permissions": "664"
        }
    ]
}

User Configuration

Define system users:

Users

array

Array of user configurations

User Fields

Field	Type	Description
`Name`	string	Username (required)
`UID`	string	User ID (0-60000)
`Password`	string	Password or hash
`PasswordHashed`	boolean	Whether password is hashed
`PasswordExpiresDays`	number	Days until expiration (0-99999, -1 for never)
`SSHPubKeyPaths`	array	SSH public key file paths
`PrimaryGroup`	string	Primary group name
`SecondaryGroups`	array	Secondary group names
`StartupCommand`	string	Shell/command for user
`HomeDirectory`	string	Home directory path

User Examples

"Users": [
    {
        "Name": "root",
        "PasswordHashed": true,
        "Password": "$6$somesalt$hashedpassword",
        "_comment": "Generated with: openssl passwd -6 -salt <SALT> <PASSWORD>"
    },
    {
        "Name": "azureuser",
        "Password": "Welcome123!",
        "UID": "1001",
        "PrimaryGroup": "users",
        "SecondaryGroups": ["wheel", "docker"],
        "SSHPubKeyPaths": ["keys/authorized_keys"]
    }
]

Network Configuration

Configure network interfaces:

Networks

array

Array of network interface configurations

Network Fields

BootProto: Protocol (dhcp or static)
GateWay: Gateway IP address
Ip: Static IP address
NetMask: Network mask
OnBoot: Enable on boot
NameServers: Array of DNS servers
Device: Network device name

"Networks": [
    {
        "BootProto": "dhcp",
        "GateWay": "192.168.20.4",
        "Ip": "192.169.20.148",
        "NetMask": "255.255.255.0",
        "OnBoot": false,
        "NameServers": ["192.168.30.23"],
        "Device": "eth0"
    }
]

Package Repositories (ISO Only)

Define custom package repositories for ISO installers:

PackageRepos

array

Array of package repository configurations

Repository Fields

Name

string

required

Repository name

BaseUrl

string

required

Repository base URL

Install

boolean

Install repo file into final image. Default: false

GPGCheck

boolean

Verify package signatures. Default: true

RepoGPGCheck

boolean

Verify repository metadata. Default: true

GPGKeys

string

Space-separated GPG key paths (e.g., file:///path/to/key)

"PackageRepos": [
    {
        "Name": "PackageMicrosoftComMirror",
        "BaseUrl": "https://contoso.com/pmc-mirror/$releasever/prod/base/$basearch",
        "Install": false
    },
    {
        "Name": "MyCopyOfOfficialRepo",
        "BaseUrl": "https://contoso.com/cbl-mariner-custom-packages/$releasever/prod/base/$basearch",
        "Install": true,
        "GPGCheck": true,
        "GPGKeys": "file:///etc/pki/rpm-gpg/my-custom-key"
    }
]

Custom repo keys must be provisioned via AdditionalFiles for installed repos.

Size Optimization

Disable Documentation and Locales

DisableRpmDocs

boolean

Exclude RPM documentation from image

OverrideRpmLocales

string

Locale setting: NONE or specific locales (e.g., en:fr:es)

"DisableRpmDocs": true,
"OverrideRpmLocales": "NONE"

Custom Locales

"OverrideRpmLocales": "en:fr:es"

Settings are stored in /usr/lib/rpm/macros.d/macros.installercustomizations_*. To restore on installed system, remove the macro files and run tdnf -y reinstall $(rpm -qa).

Advanced Options

RemoveRpmDb

boolean

Remove RPM database after installation (breaks package managers)

PreserveTdnfCache

boolean

Keep tdnf cache intact (default cleans cache to save space)

EnableHidepid

boolean

Enable stricter hidepid option in /proc (hidepid=2)

Complete Example

{
    "SystemConfigs": [
        {
            "Name": "Standard",
            "BootType": "efi",
            "Hostname": "azurelinux",
            "PartitionSettings": [
                {
                    "ID": "boot",
                    "MountPoint": "/boot/efi",
                    "MountOptions": "umask=0077"
                },
                {
                    "ID": "rootfs",
                    "MountPoint": "/"
                }
            ],
            "PackageLists": [
                "packagelists/core-packages-image.json",
                "packagelists/cloud-init-packages.json"
            ],
            "KernelOptions": {
                "default": "kernel"
            },
            "KernelCommandLine": {
                "ExtraCommandLine": "console=ttyS0"
            },
            "PostInstallScripts": [
                {
                    "Path": "scripts/configure-system.sh"
                }
            ],
            "AdditionalFiles": {
                "configs/cloud-init.cfg": "/etc/cloud/cloud.cfg"
            },
            "DisableRpmDocs": true
        }
    ]
}

Overview

Quick Start

Building

Architecture

Image Configuration

Security

Advanced Topics

Package Management

Contributing

​System Configuration Structure

​Partition Settings

​Basic Partition Settings

​Using Partition Labels

​Differential Images

​Kernel Configuration

​Kernel Options

​Kernel Command Line

​IMA and Custom Parameters

​FIPS Mode

​SELinux

​CGroup v2

​Boot Configuration

​Customization Scripts

​Script Format

​PreInstall Scripts

​Additional Files

​Simple File Copy

​Multiple Destinations and Permissions

​User Configuration

​User Fields

​User Examples

​Network Configuration

​Network Fields

​Package Repositories (ISO Only)

​Repository Fields

​Size Optimization

​Disable Documentation and Locales

​Custom Locales

​Advanced Options

​Complete Example

​Next Steps

Package Lists

Examples

Build docs developers (and LLMs) love

System Configuration Structure

Partition Settings

Basic Partition Settings

Using Partition Labels

Differential Images

Kernel Configuration

Kernel Options

Kernel Command Line

IMA and Custom Parameters

FIPS Mode

SELinux

CGroup v2

Boot Configuration

Customization Scripts

Script Format

PreInstall Scripts

Additional Files

Simple File Copy

Multiple Destinations and Permissions

User Configuration

User Fields

User Examples

Network Configuration

Network Fields

Package Repositories (ISO Only)

Repository Fields

Size Optimization

Disable Documentation and Locales

Custom Locales

Advanced Options

Complete Example

Next Steps