Automated Installation Using Agama

Agama as a service-based Linux installer capable of performing both interactive and unattended installations. You can provide Agama a JSON profile file detailing the initial system state, such as user authentication, partitioning, networking and software selection. On receiving the profile and instruction for installation from one of its supported clients, Agama installs your target system accordingly. Users can interact with and control the installation process using Agama's web-based user interface, command-line interface and HTTP API, facilitating automation and integration into existing workflows.

While Agama reuses many principles and internal components from previous SUSE installers like YaST and AutoYaST, and offers a high level of backwards compatibility for unattended installations, it is not a 100% compatible drop-in replacement for all AutoYaST features. Agama focuses only on the installation process rather than being a general configuration tool.

Figure 1: Agama server client architecture #

 

Agamaoffers its installation service by exposing an HTTP API, which you can use interactively from a web-based interface and a command-line interface (CLI), or provide a JSON profile to Agama for automated installation of a target system. Using the HTTP API you can also integrate with custom scripts and deployment tools. The benefits of using Agama for automated installation are as follows:

Agama profile configuration is defined using a JSON document. It contains several sections that are necessary for describing the installation parameters for a customized system. At a high level, the profile consists of the following sections:

{
  "product": {}, 1
  "root": {}, 2
  "user": {}, 3
  "localization": {}, 4
  "hostname": {}, 5
  "software": {}, 6
  "storage": {}, 7
  "bootloader": {}, 8
  "network": {}, 9
  "security": {}, 10
  "scripts": {}, 11
  "files": {}, 12
  "legacyAutoyastStorage": {}, 13
  "iscsi": {}, 14
  "dasd": {} 15
}

You can also describe profiles using Jsonnet, which is a superset of JSON. Jsonnet offers features like variables, functions and more convenient syntax, making profiles more readable, concise, and dynamic for injecting hardware information at runtime.

For more information on the JSON and Jsonnet profiles, refer to the resources mentioned in the Section 9, “For more information” section. The upstream resources usually contains most updated information and examples about the profiles.

A minimal Agama JSON profile must at least include sections for product identification, product registration, and credentials for the root user. Agama uses the defaults for the rest of the profile. As a best practice, you should also configure the following as a best practice:

{
  "product": {
    "id": "SUSE Linux Enterprise Server for SAP applications 16.0",
    "registrationCode": "REGISTRATION-CODE",
    "registrationEmail": "EMAIL",
  },
  "hostname": {
    "static": "STATIC-HOSTNAME",
    "transient": "TRANSIENT-HOSTNAME"
  },
  "root": {
    "hashedPassword": true,
    "password": "HASHED-ROOT-PASSWORD", 1
    "sshPublicKey": "SSH-PUBLIC-KEY", 2
  },
  "user": {
    "hashedPassword": false,
    "autologin": false,
    "fullName": "FULL-NAME",
    "userName": "USERNAME",
    "password": "PLAINTEXT-PASSWORD"
  },
  "localization": {
    "language": "LANGUAGE",
    "keyboard": "KEYBOARD-LAYOUT",
    "timezone": "TIMEZONE"
  }
}

> sudo openssl passwd -6

> sudo ssh-keygen -t rsa -b 4096 -C "YOUR-EMAIL@EXAMPLE.COM"

To evaluate the correctness of the profile, run the following command:

> sudo agama profile validate AGAMA-PROFILE.json

The product section defines the SUSE product to be installed and includes optional registration data and add-on modules. This is essential for systems requiring access to subscription repositories or additional functionality.

"product": {
  "id": "SUSE Linux Enterprise Server for SAP applications 16.0",
  "registrationCode": "REGISTRATION-CODE",
  "registrationEmail": "EMAIL-ADDRESS",
  "registrationUrl": "REGISTRATION-URL",
  "addons": [
    {
      "id": "ADDON-ID",
      "version": "ADDON-VERSION",
      "registrationCode": "ADDON-REGISTRATION-CODE"
    }
  ]
}

This section contains the following fields:

The hostname section sets the system's static and transient hostname. The static hostname is persistent across reboots, while the transient hostname is used temporarily at runtime and may be overridden by network services like DHCP.

"hostname": {
  "static": "STATIC-HOSTNAME",
  "transient": "TRANSIENT-HOSTNAME"
}

This section contains the following fields:

The root section defines authentication settings for the system's root account. This includes a root password (either plain or pre-hashed) and an optional SSH public key for remote access.

"root": {
  "hashedPassword": true,
  "password": "HASHED-ROOT-PASSWORD",
  "sshPublicKey": "SSH-PUBLIC-KEY"
}

This section contains the following fields:

The user section defines the initial non-root user account created during installation. This includes the user's full name, login name, password (plain or hashed), and optional automatic login preference.

"user": {
  "hashedPassword": false,
  "fullName": "FULL-NAME",
  "userName": "LOGIN-NAME",
  "password": "USER-PASSWORD",
  "autologin": false
}

This section contains the following fields:

The localization section defines the system language, keyboard layout, and time zone settings. These parameters determine the default locale and input behavior after installation.

"localization": {
  "language": "LANGUAGE-ID",
  "keyboard": "KEYBOARD-LAYOUT",
  "timezone": "TIMEZONE"
}

This section contains the following fields:

The software section defines which software components are installed on the system via SUSE's pattern and package management infrastructure.

"software": {
  "patterns": [
    "minimal_base",
    "app_server"
  ],
  "packages": [
    "vim",
    "htop",
    "curl"
  ]
}

This section contains the following fields:

Note: Trust the GPG key for the Package Hub repository

When enabling SUSE Package Hub during a manual installation, users are prompted to trust the repository's GPG key. To trust the key automatically during an unattended installation, use the following snippet:

{
  product: {
    id: 'SLES',
    registrationCode: 'SLES_REG_CODE',
    addons: [
      {
        id: 'PackageHub',
      }
    ]
  },
  questions: {
    policy: 'auto',
    answers: [
      {
        answer: 'Trust',
        class: 'software.import_gpg',
        data: {
          fingerprint: 'BF3F 9A67 D3A2 FF98 A73F 5E07 488C 583D 287A 0027',
          name: 'openSUSE Backports for SUSE Linux 16 sle-backports-202500514@opensuse.org',
          id: '488C583D287A0027'
        }
      }
    ]
  }
}

The storage section defines the system's target disk layout, such as devices, partitions and volume management, to be applied during installation. This field references the Agama storage schema, which is referenced from the profile schema.

Note: Advanced storage configuration

An exhaustive description of all possible storage configuration using Agama is beyond the scope of this section, as it will need a careful consideration of the storage model schema. For information on advanced storage configuration, refer to the section Section 7, “Advanced storage configuration using Agama profiles”.

"storage": {
  "drives": [ ... ],
  "volumeGroups": [ ... ],
  "mdRaids": [ ... ],
  "boot": { ... }
}

A storage section contains several entries describing how to configure the corresponding storage devices, and some extra entries such as boot to setup some general aspects that influence the final layout.

Each volume group or software RAID can represent a new logical device to be created, or an existing device from the system to be processed. Entries below drives represent devices that can be used as regular disks, which includes removable and fixed disks, SD cards, DASD or zFCP devices, iSCSI disks, and multipath devices. Those entries always correspond to devices that can be found at the system, because Agama cannot create that kind of devices.

Note: Compatibility with legacy AutoYaST storage

In some cases, storage can be replaced by the legacyAutoyastStorage section. This section supports everything offered by the partitioning section of the AutoYaST profile. However, Agama does not validate this special section—be careful to provide valid AutoYaST options.

The bootloader section defines boot-time behavior, including whether to pause at the boot menu and what extra kernel parameters to pass. It affects the installed system's GRUB configuration.

"bootloader": {
  "stopOnBootMenu": false,
  "timeout": 5,
  "extraKernelParams": "KERNEL-PARAMETERS"
}

This section contains the following fields:

The network section defines one or more network connections to be configured during installation. Each connection supports IP setup, interface binding, wireless settings, bonding, bridging, and optional enterprise-grade authentication mechanisms like IEEE 802.1X.

Example 10: Sample network configuration for an Agama installation profile #

 

"network": {
  "connections": [
    {
      "id": "ETH0-CONNECTION",
      "interface": "eth0",
      "method4": "manual",
      "addresses": ["192.168.100.10/24"],
      "gateway4": "192.168.100.1",
      "nameservers": ["1.1.1.1", "8.8.8.8"],
      "autoconnect": true
    },
    {
      "id": "WIFI-HOME",
      "interface": "wlan0",
      "method4": "auto",
      "wireless": {
        "ssid": "MYSSID",
        "password": "MYWIFIPASSWORD",
        "security": "wpa-psk"
      }
    },
    {
      "id": "BRIDGE0",
      "interface": "br0",
      "method4": "auto",
      "bridge": {
        "stp": true,
        "forwardDelay": 15,
        "ports": ["eth0", "eth1"]
      }
    },
    {
      "id": "BOND0",
      "interface": "bond0",
      "method4": "manual",
      "addresses": ["10.0.0.100/24"],
      "gateway4": "10.0.0.1",
      "bond": {
        "mode": "active-backup",
        "options": "miimon=100",
        "ports": ["eth2", "eth3"]
      }
    },
    {
      "id": "SECURE-ETH",
      "interface": "eth4",
      "method4": "auto",
      "ieee-8021x": { 1
        "eap": ["peap"],
        "identity": "USERNAME",
        "password": "PASSWORD",
        "caCert": "/etc/certs/ca.pem"
      }
    }
  ]
}

1

Note Support for IEEE 802.1X authentication is intended for advanced enterprise deployments where authentication is required at the link layer, before IP is assigned. This commonly involves integration with RADIUS and certificate-based trust. Misconfiguration can result in complete network inaccessibility. Refer to systemd-networkd documentation for authoritative guidance.

This section contains the following connection attributes:

The security section allows you to add trusted SSL certificates to the installed system. This is useful when connecting to internal package mirrors, registration servers, or other TLS services that require non-default certificate authorities.

"security": {
  "sslCertificates": [
    {
      "fingerprint": "FINGERPRINT",
      "algorithm": "SHA256"
    }
  ]
}

This section contains the following fields:

To verify the fingerprint of a certificate in PEM format:

> sudo openssl x509 -in FILE.pem -noout -fingerprint -sha256

Trusted certificates can be installed permanently by placing them in /etc/pki/trust/anchors and then executing:

> sudo update-ca-certificates

The scripts section allows you to define custom shell scripts to be executed at different stages of the SUSE installation lifecycle. These scripts can be embedded inline, fetched from a URL, and optionally executed in a chroot environment (where applicable).

"scripts": {
  "pre": [
    {
      "name": "PRE-CHECK-DISK.sh",
      "content": "#!/bin/bash\nif [ ! -e /dev/sda ]; then echo 'Disk not found' >&2; exit 1; fi"
    }
  ],
  "postPartitioning": [
    {
      "name": "CREATE-MOUNTS.sh",
      "url": "http://EXAMPLE.COM/SCRIPTS/MOUNTS.sh"
    }
  ],
  "post": [
    {
      "name": "FINALIZE-INSTALL.sh",
      "content": "#!/bin/bash\necho 'Installation complete'",
      "chroot": true
    }
  ],
  "init": [
    {
      "name": "FIRST-BOOT.sh",
      "content": "#!/bin/bash\necho 'System booted for the first time'"
    }
  ]
}

This section defines the following script categories:

Each script object may contain one of the following keys:

The files section allows deployment of custom user-defined files into the installed system. These files are written just before post-installation scripts run and can be useful for configuring services, dropping keys, or overriding system files.

"files": [
  {
    "destination": "ABSOLUTE-FILE-PATH",
    "content": "FILE-CONTENT",
    "permissions": "0644",
    "user": "USERNAME",
    "group": "GROUPNAME"
  }
]

This section contains an array of file definitions. Each entry supports the following fields:

The legacyAutoyastStorage section allows reuse of AutoYaST-style storage definitions by expressing them in JSON. It accepts an array of opaque objects directly representing the legacy partitioning structure, allowing migration or backward compatibility for existing storage configurations.

"legacyAutoyastStorage": [
  {
    "partitions": {
      "partition": [
        {
          "device": "/dev/sda1",
          "mount": "/",
          "size": "20G",
          "filesystem": "ext4"
        },
        {
          "device": "/dev/sda2",
          "mount": "swap",
          "size": "4G",
          "filesystem": "swap"
        }
      ]
    }
  }
]

This section contains the following:

The iscsi section defines parameters required for configuring iSCSI targets that should be discovered and mounted during system installation. This is particularly relevant for systems that boot from SAN or use iSCSI-based storage volumes.

"iscsi": {
  "initiatorName": "IQN-OF-INITIATOR",
  "targets": [
    {
      "address": "TARGET-IP",
      "port": 3260,
      "target": "IQN-OF-TARGET",
      "user": "CHAP-USERNAME",
      "password": "CHAP-PASSWORD",
      "autoLogin": true
    }
  ]
}

This section contains the following configuration keys:

The dasd section is used to activate, configure, or format Direct Access Storage Device (DASD) volumes on IBM Z (s390x) systems. It is relevant only when installing SUSE on mainframe hardware.

"dasd": {
  "devices": [
    {
      "channel": "0.0.1234",
      "state": "active",
      "format": true,
      "diag": false
    },
    {
      "channel": "0.0.5678",
      "state": "offline"
    }
  ]
}

This section defines the following keys:

Reusing existing AutoYaST profiles in Agama provides a pragmatic starting point for teams migrating to the new installer without discarding prior investments. Although direct compatibility is limited, leveraging AutoYaST profiles accelerates transition efforts by retaining core configuration logic, organizational conventions, and validated deployment workflows.

Using AutoYaST profiles in Agama has the following benefits:

While reusing AutoYaST profiles in Agama may provide a head start during migration, it also introduces significant limitations. The fundamental differences in schema structure, execution model, and configuration philosophy mean that AutoYaST-based profiles can constrain the effectiveness and clarity of Agama workflows if carried over directly.

Using AutoYaST profiles in Agama has the following limitations:

Agama supports loading AutoYaST profiles as part of its transitional support for legacy automation systems. This allows administrators to reuse existing configuration assets while gradually migrating to the native Agama profile format. Several loading mechanisms are available depending on the deployment context and profile structure.

Converting AutoYaST profiles to Agama profiles involves transforming the original XML into Agama's JSON or Jsonnet format. This procedure outlines the recommended steps using the Agama CLI.

Multipath in Linux is a device mapper framework that provides redundancy and improved performance for storage devices by creating a single logical device from multiple physical paths to the same storage target. This architecture prevents storage I/O interruptions due to hardware failures while enabling load balancing across paths, and is commonly used in enterprise environments.

To enable this capability, the multipath subsystem must be activated by Agama during installation of SUSE Linux Enterprise. Once activated, multipath affects all devices system-wide, meaning all disks must be referenced exclusively by their corresponding multipath device names. Agama currently provides several mechanisms for users to activate multipath support.

By default, you should have access to all the different ways of forced and conditional activation of multipath.

If you are certain that the system uses multipath, the most reliable method to ensure that Agama activates the corresponding subsystems is to enable the environment variable LIBSTORAGE_MULTIPATH_AUTOSTART at the time of boot.

If multipath activation is not enforced through the boot parameter, Agama attempts to detect multipath devices in the system. When detected, Agama either prompts you to confirm multipath activation, or proceeds with unattended installation based on the answer provided in the Agama profile.

Warning: Unreliable multipath detection

Detection of multipath devices using Agama is not fully reliable. If you are sure that the system uses multipath devices, we recommend using the method of enabling the necessary boot parameters.

If you are performing a manual installation of SUSE Linux Enterprise using Agama, you can activate multipath support by adding the LIBSTORAGE_MULTIPATH_AUTOSTART=1 boot parameter, or confirming multipath activation using the web or command-line interfaces of Agama during the installation process.

If you are performing an unattended installation using Agama, edit the Agama profile to include answer to the question of multipath activation, and pass the path to the profile as the value of the inst.auto boot parameter.

Depending on the chosen method of multipath activation, use one of more of the following troubleshooting tips:

A storage section contains several entries describing how to configure the corresponding storage devices, and some extra entries such as boot to setup some general aspects that influence the final layout.

Each volume group or software RAID can represent a new logical device to be created, or an existing device from the system to be processed. Entries below drives represent devices that can be used as regular disks, which includes removable and fixed disks, SD cards, DASD or zFCP devices, iSCSI disks, and multipath devices. Those entries always correspond to devices that can be found at the system, because Agama cannot create that kind of devices.

"storage": {
  "drives": [ ... ],
  "volumeGroups": [ ... ],
  "mdRaids": [ ... ],
  "boot": { ... }
}

Note: Compatibility with legacy AutoYaST storage

In some cases, storage can be replaced by the legacyAutoyastStorage section. This section supports everything offered by the partitioning section of the AutoYaST profile. However, Agama does not validate this special section—be careful to provide valid AutoYaST options.

The following sections illustrate certain common use-cases with examples. Before execution, it is recommended to validate the configurations using the tools provided by Agama.

The drives collection contains several optional fields, some of which are mutually exclusive.

{
  "alias": "...",
  "search": { ... },
  "encryption": { ... },
  "filesystem": { ... },
  "partitions": [ ... ],
  "ptableType": "..."
}

Usually, a device represented by a drive entry is divided into several partitions. Each entry of partitions has the following structure with several optional fields:

{
  "alias": "...",
  "search": { ... },
  "id": "...",
  "size": { ... },
  "encryption": { ... },
  "filesystem": { ... },
  "delete": ...,
  "deleteIfNeeded": ...
}

Drives and partitions can be combined such that the one disk is used to create partitions and the other is directly formatted.

"storage": {
  "drives": [
    {
      "partitions": [
        {
          "filesystem": { "path": "/" },
          "size": { "min": "10 GiB" }
        },
        {
          "filesystem": { "path": "swap" },
          "size": "2 GiB"
        }
      ]
    },
    {
      "filesystem": { "path": "/home" },
    }
  ]
}

An entry from volumeGroups can have the following properties:

{
  "alias": "...",
  "name": "...",
  "search": { ... },
  "physicalVolumes": [ ... ],
  "logicalVolumes": [ ... ],
  "peSize": ... ,
  "delete": ...
}

Entries of logicalVolumes are relatively similar to the ones used to describe partitions.

{
  "alias": "...",
  "search": { ... },
  "name": "...",
  "size": { ... },
  "encryption": { ... },
  "filesystem": { ... },
  "pool": ...,
  "usedPool": "...",
  "stripes": ...,
  "stripeSize": ...,
  "delete": ...,
  "deleteIfNeeded": ...
}

To understand how all the previously described elements fit together, consider the following example in which the first disk of the system is partitioned and a volume group is created on top of that partition after encryption, to allocate two file systems.

"storage": {
  "drives": [
    {
      "partitions": [
        {
          "alias": "pv",
          "id": "lvm",
          "size": { "min": "12 GiB" },
          "encryption": {
            "luks2": { "password": "my secret passphrase" }
          }
        }
      ]
    }
  ],
  "volumeGroups": [
    {
      "name": "system",
      "physicalVolumes": [ "pv" ],
      "logicalVolumes": [
        {
          "size":   { "min": "10 GiB" },
          "filesystem": { "path": "/", "type": "btrfs" }
        },
        {
          "size":   "2 GiB",
          "filesystem": { "path": "swap", "type": "swap" }
        }
      ]
    }
  ]
}

Agama can also manage software-defined MD RAID arrays represented as entries at the mdRaids collection.

{
  "alias": "...",
  "name": "...",
  "search": { ... },
  "level": "...",
  "chunkSize": ... ,
  "devices": [ ... ],
  "size": { ... },
  "encryption": { ... },
  "filesystem": { ... },
  "partitions": [ ... ],
  "ptableType": "...",
  "delete": ...
}

The devices property is used to specify the devices that act as members of the RAID.

"storage": {
  "drives": [
    {
      "search": "/dev/sda",
      "partitions": [
        { "alias": "sda-40", "size": "40 GiB" }
      ]
    },
    {
      "search": "/dev/sdb",
      "partitions": [
        { "alias": "sdb-40", "size": "40 GiB" }
      ]
    }
  ],
  "mdRaids": [
    {
      "devices": [ "sda-40", "sdb-40" ],
      "level": "raid0"
    }
  ]
}

When a section in the profile describes modification and deletion of devices, the description must match with one or more devices from the system. If a description matches several devices, the same operations are applied to all of them. This approach is useful in several situations, such as applying the same partitioning schema to several disks or deleting all partitions of a disk that match a given criteria.

Matching is performed using a search subsection, as illustrated below. By default, all devices in the scope fitting the conditions are matched. You can limit the number of devices that match using max. The following example shows how you can use several search sections to find the three biggest disks in the system, delete all partitions bigger than 1 GiB within them and create new partitions of type RAID.

"storage": {
  "drives": [
    {
      "search": {
        "sort": { "size": "desc" },
        "max": 3
      },
      "partitions": [
        {
          "search": {
            "condition": { "size": { "greater": "1 GiB" } }
          },
          "delete": true
        },
        {
          "alias": "newRaidPart",
          "id": "raid",
          "size": { "min": "1 GiB" }
        }
      ]
    }
  ]
}

The scope of each search depends on the place in the profile of the search section. In the example, the devices from the system that are considered as possible candidates. A search section inside the description of an MD RAID only matches the software RAID devices. A search section inside the partitions subsection of that RAID description only matches the partitions of RAIDs that have matched the conditions of the most external search.

A device can never match two different sections of the Agama profile. When several sections at the same level contain a search subsection, devices are matched in the order the sections appear on the profile.

"storage": {
  "drives": [
    {
      "search": {
        "sort": { "size": "desc" },
        "max": 1
      },
      "alias": "biggest"
    },
    {
      "search": {
        "sort": { "size": "desc" },
        "max": 1
      },
      "alias": "secondBiggest"
    }
  ]
}

An empty search matches all devices in the scope. For example, the configuration given below deletes all the partitions of the chosen disk, but only if the disk contains partitions.

"storage": {
  "drives": [
    {
      "partitions": [
        { "search": {}, "delete": true }
      ]
    }
  ]
}

If there is not a single system device matching the scope and the conditions of a given search, then ifNotFound is used. If the value is skip, the device definition is ignored. If the value is "error" the whole process is aborted.

Entries on drives are different from all other subsections describing devices because drives can only be matched to existing devices. If search is omitted for a drive, it is considered to contain the following configuration:

{
  "search": {
    "sort": "name",
    "max": 1,
    "ifNotFound": "error"
  }
}

When the syntax of a search subsection becomes cumbersome, you can use simple strings.

You can use search to find a device by its name. For example:

{ "search": "/dev/sda" }

The string * allows to match all the devices from the current context, if any. This is specially useful to match all partitions or logical volumes in a device, irrespective of whether there is any. For example, the two following search sections are equivalent:

{ "search": "*" }

{ "search": { "ifNotFound": "skip" } }

At certain times, it is necessary to reference other devices as part of the specification of an LVM volume group or RAID. Those devices can be existing system devices, or devices that will be created as response to another entry of the Agama profile. For that purpose, you can use alias.

"storage": {
  "drives": [
    {
      "partitions": [
        { "size": "50 GiB", "id": "lvm", "alias": "newPV" }
      ]
    }
   ],
   "volumeGroups": [
    {
      "name": "newVG",
      "physicalVolumes": [ "newPV" ],
      "logicalVolumes": [ { "name": "data", "size": "20 GiB" } ]
    }
  ]
}

If a section matching several existing devices contains an alias, that alias is considered as a reference to all the devices. Consider the following equivalent examples that assumes there are at least two disks in the system:

"storage": {
  "drives": [
    {
      "search": {
        "sort": { "size": "desc" },
        "max": 1,
      },
      "alias": "biggest"
    },
    {
      "search": {
        "sort": { "size": "desc" },
        "max": 1,
      },
      "alias": "secondBiggest"
    }
  ],
  "mdRaids": [
    {
      "devices": [ "biggest", "secondBiggest" ],
      "level": "raid0"
    }
  ]
}

"storage": {
  "drives": [
    {
      "search": {
        "sort": { "size": "desc" },
        "max": 2,
      },
      "alias": "big"
    }
  ],
  "mdRaids": [
    {
      "devices": [ "big" ],
      "level": "raid0"
    }
  ]
}

When configuring storage in the Agama profile, you must specify the desired size for a new device or the target size when resizing an existing one. The schema allows for flexible size specification. The most common method is using a human-readable string that can be parsed into a valid size. For example, 10 GiB. Alternatively, you can provide a size as an array (a tuple) containing a minimum size and an optional maximum size. The resulting size will be between these two thresholds. If the maximum is omitted, the device will expand to consume all available contiguous space, respecting other specified size constraints.

For configurations targeting existing partitions or Logical Volumes (LVs)—which must include a search section—the special keyword current can be used as a minimum or maximum size limit. The use of current and how it affects resizing the corresponding devices is explained separately.

If the size property is completely omitted for an existing device (for example, combined with search), Agama acts as if both minimum and maximum limits were set to current. This characteristic implies that the partition or logical volume are not be resized. If the size is omitted for a device that will be created but includes a file system entry specifying a mount point, Agama can determine the size limits by applying the settings of the installation product. In Agama terminology, the product is the operating system being installed, and it specifies the default size ranges for its relevant file systems, such as /, swap and /home.

You can use the boot entry to configure whether Agama should calculate and create extra partitions needed for booting. The behavior is same when using an alias. If the device is not specified, Agama takes the location of the root file system as reference.

"storage": {
  "drives": [
    {
      "search": "/dev/sda",
      "alias": "bootDisk"
    },
    {
      "search": "/dev/sdb",
      "partitions": [
        { "filesystem": { "path": "/" } }
      ]
    }
  ],
  "boot": {
    "configure": true,
    "device": "bootDisk"
  }
}

The entries for both filesystem and encryption contains a reuse flag with a default value of false. You can use it in combination with search to specify that the device must not be re-formatted or re-encrypted.

The storage configuration proposal must allow defining how to manage existing storage components, including partitions, LVM logical volumes, MD RAIDs, and LVM volume groups. A search mechanism is employed to match a partition or LVM logical volume definition with one or more devices already present on the system. Once a match is made, you can specify the required action.

The component can be marked to be deleted unconditionally, or deleted if needed to free space for newly defined devices. It can also be shrunk to a necessary size or shrunk or extended to a specific size or range. It is even possible to express combined actions, like attempting to shrink a component first and only proceeding to delete it if shrinking doesn't free up enough space.

Deletion is achieved with the corresponding delete flag for unconditional deletion or the deleteIfNeeded flag for conditional deletion. If either of these flags is active for a partition, it is illogical to specify any other usage for it, such as declaring a file system. For example, you can configure the proposal to unconditionally delete partition number 1 and then conditionally delete other partitions as needed to secure the space for a new 30 Gib partition.

"storage": {
  "drives": [
    {
      "partitions": [
        {
          "search": {
            "condition": { "number": 1 }
          },
          "delete": true
        },
        { "search": {}, "deleteIfNeeded": true },
        { "size": "30 GiB" }
      ]
    }
  ]
}

Often some partitions or logical volumes are shrunk only to make space for the declared devices. But because resizing is not a destructive operation, you can declare a given partition to be resized (shrunk or extended), then formatted and/or mounted.

Note: Limitation of resizing

Resizing a partition can be limited depending on its content and the file system type.

Combining search and resize is enough to indicate that Agama is expected to resize a given partition, if possible. The keyword current can be used as min and/or max for the size range, and it is always equivalent to the exact original size of the device. The simplest way to use current is to just specify that the matched device should keep its original size. That is the default for searched (and found) devices, if size is completely omitted.

"storage": {
  "drives": [
    {
      "partitions": [
        {
          "search": {
            "condition": { "number": 1 }
          },
          "size": { "min": "current", "max": "current" }
        }
      ]
    }
  ]
}

You can use other combinations to specify how a device could be resized, if possible. See the following examples with explanatory file system labels.

Warning

The condition fsLabel is not yet implemented.

"storage": {
  "drives": [
    {
      "partitions": [
        {
          "search": {
            "condition": { "fsLabel": "shrinkIfNeeded" }
          },
          "size": { "min": 0, "max": "current" }
        },
        {
          "search": {
            "condition": { "fsLabel": "resizeToFixedSize" }
          },
          "size": "15 GiB"
        },
        {
          "search": {
            "condition": { "fsLabel": "resizeByRange" }
          },
          "size": { "min": "10 GiB", "max": "50 GiB" }
        },
        {
          "search": {
            "condition": { "fsLabel": "growAsMuchAsPossible" }
          },
          "size": { "min": "current" }
        },
      ]
    }
  ]
}

When the size limits are specified as a combination of current and a fixed value, ensure that the resulting min is not bigger than the resulting max.

Both deleteIfNeeded and a size range can be combined to indicate that Agama should make space first, by shrinking the partitions and deleting them only if shrinking is not enough.

"storage": {
  "drives": [
    {
      "partitions": [
        {
          "search": {},
          "size": { "min": 0, "max": "current" },
          "deleteIfNeeded": true
        }
      ]
    }
  ]
}

Every product provides a configuration which defines the storage volumes. For example, feasible file systems for root and default partitions to create. The default or mandatory product volumes can be automatically generated by using a generate section in the partitions or logicalVolumes sections.

"storage": {
  "drives": [
    {
      "partitions": [
        { "generate": "default" }
      ]
    }
  ]
}

The generate section allows creating the product volumes without explicitly writing all of them. The configuration above would be equivalent to the following:

"storage": {
  "drives": [
    {
      "partitions": [
        { "filesystem": { "path": "/" } },
        { "filesystem": { "path": "/home" } },
        { "filesystem": { "path": "swap" } }
      ]
    }
  ]
}

If any path is explicitly defined, the generate section will not generate a volume for it. For example, with the following configuration, only root and swap would be automatically added.

"storage": {
  "drives": [
    {
      "partitions": [
        { "generate": "default" },
        { "filesystem": { "path": "/home" } }
      ]
    }
  ]
}

The auto-generated volumes can be also configured. For example, for encrypting the partitions:

"storage": {
  "drives": [
    {
      "partitions": [
        {
          "generate": {
            "partitions": "default",
            "encryption": {
              "luks1": { "password": "12345" }
            }
          }
        }
      ]
    }
  ]
}

The mandatory keyword can be used for generating only the mandatory partitions or logical volumes:

"storage": {
  "volumeGroups": [
    {
      "name": "system",
      "logicalVolumes": [
        { "generate": "mandatory" }
      ]
    }
  ]
}

You can configure volume groups to explicitly use a set of devices as physical volumes. The aliases of the devices to use are added to the list of physical volumes:

"storage": {
  "drives": [
    {
      "search": "/dev/vda",
      "partitions": [
        { "alias": "pv2", "size": "100 GiB" },
        { "alias": "pv1", "size": "20 GiB" }
      ]
    }
  ],
  "volumeGroups": [
    {
      "name": "system",
      "physicalVolumes": ["pv1", "pv2"]
    }
  ]
}

The physical volumes can be automatically generated too, by simply indicating the target devices in which to create the partitions. For that, a generate section is added to the list of physical volumes:

"storage": {
  "drives": [
    {
      "search": "/dev/vda",
      "alias": "pvs-disk"
    }
  ],
  "volumeGroups": [
    {
      "name": "system",
      "physicalVolumes": [
        { "generate": ["pvs-disk"] }
      ]
    }
  ]
}

If the auto-generated physical volumes have to be encrypted, then the encryption config is added to the generate section:

"storage": {
  "drives": [
    {
      "search": "/dev/vda",
      "alias": "pvs-disk"
    }
  ],
  "volumeGroups": [
    {
      "name": "system",
      "physicalVolumes": [
        {
          "generate": {
            "targetDevices": ["pvs-disk"],
            "encryption": {
              "luks2": { "password": "12345" }
            }
          }
        }
      ]
    }
  ]
}

This table highlights the fundamental differences in design philosophy and approach between AutoYaST and Agama.

This section provides a detailed comparison and translation map between the major sections and modules of AutoYaST and their equivalents (or lack thereof) in the Agama profile schema. Each subsection addresses a particular functional area, indicating how configuration responsibilities are split or restructured in Agama, and clearly states where support is partial, planned, or unavailable.

Note: Granular support status for AutoYaST elements

For a more granular information on the compatibility and support status for AutoYaST elements in Agama profiles as compared to what is presented here, refer to the upstream documentation https://agama-project.github.io/docs/user/autoyast/reference.

The following table lists AutoYaST profile sections that are currently not supported by Agama. These modules either have no equivalent functionality in Agama, are considered legacy or niche, or are planned for future implementation. This list is essential for users migrating from AutoYaST to avoid misconfiguration or unmet expectations.