Automated Installation Using Agama

Agama is a service-based Linux installer capable of performing both interactive and unattended installations. You can provide Agama with a JSON profile file detailing the initial system state, such as user authentication, partitioning, networking and software selection. On receiving the profile and instructions 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 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, it focuses only on the installation process rather than being a general configuration tool. See AutoYaST compatibility for how it relates to AutoYaST.

Figure 1: Agama client-server architecture #

 

Agama offers its installation service through an HTTP API, which you can use interactively from a Web 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:

The 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
  "l10n": {}, 4
  "hostname": {}, 5
  "software": {}, 6
  "storage": {}, 7
  "bootloader": {}, 8
  "network": {}, 9
  "security": {}, 10
  "scripts": {}, 11
  "files": {}, 12
  "legacyAutoyastStorage": {}, 13
  "iscsi": {}, 14
  "dasd": {}, 15
  "zfcp": {}, 16
  "ntp": {}, 17
  "access": {}, 18
  "questions": {} 19
}

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 Section 14, “For more information”. The upstream resources usually contain the most up-to-date information and examples about the profiles.

Agama and AutoYaST profiles are largely compatible for all common use cases. However, Agama profiles are not fully compatible with AutoYaST profiles, and cannot be used as a drop-in replacement without checking the compatibility. There are certain aspects of the AutoYaST profiles that are currently supported in Agama profiles, or may be supported in the future. However, there are certain other aspects that are neither currently supported in Agama profiles, nor will be supported in the future. For more information, refer to Using AutoYaST Profiles with Agama.

The product identifier of your target product, and, if applicable, a registration code and email.

A minimal Agama JSON profile only needs a product section to identify what to install, and a root section with credentials for the root user. Agama uses the defaults for the rest of the profile. As a best practice, also configure the following:

{
  "product": {
    "id": "PRODUCT_ID",
    "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,
    "fullName": "FULL_NAME",
    "userName": "USERNAME",
    "password": "PLAINTEXT_PASSWORD",
    "sshPublicKey": "SSH_PUBLIC_KEY" 3
  },
  "l10n": {
    "locale": "LOCALE",
    "keymap": "KEYMAP",
    "timezone": "TIMEZONE"
  }
}

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

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

# agama config validate AGAMA_PROFILE.json

The following profile combines several sections into one working example: product registration, root and user accounts, localization, software selection, a single-disk storage layout using the product's default partitioning, a static network connection, a boot loader timeout, and a post-installation script. Adapt the values to your own environment; see Section 5, “Details of an Agama installation profile” for every field each section accepts.

{
  "product": {
    "id": "PRODUCT_ID", 1
    "registrationCode": "REGISTRATION_CODE",
    "registrationEmail": "EMAIL"
  },
  "hostname": {
    "static": "STATIC_HOSTNAME"
  },
  "root": {
    "hashedPassword": true,
    "password": "HASHED_ROOT_PASSWORD", 2
    "sshPublicKey": "SSH_PUBLIC_KEY" 3
  },
  "user": {
    "fullName": "FULL_NAME",
    "userName": "USERNAME",
    "hashedPassword": false,
    "password": "PLAINTEXT_PASSWORD"
  },
  "l10n": {
    "locale": "LOCALE",
    "keymap": "KEYMAP",
    "timezone": "TIMEZONE"
  },
  "software": {
    "patterns": ["minimal_base", "selinux"],
    "packages": ["vim", "htop"]
  },
  "storage": {
    "drives": [
      { "partitions": [ { "generate": "default" } ] }
    ]
  },
  "network": {
    "connections": [
      {
        "id": "ETH0_CONNECTION",
        "interface": "eth0",
        "method4": "manual",
        "addresses": ["192.168.100.10/24"],
        "gateway4": "192.168.100.1",
        "nameservers": ["192.168.100.1"],
        "autoconnect": true
      }
    ]
  },
  "bootloader": {
    "timeout": 5
  },
  "scripts": {
    "post": [
      {
        "name": "enable-firewall",
        "chroot": true,
        "content": "#!/bin/bash\nsystemctl enable firewalld"
      }
    ]
  }
}

Instead of writing a profile by hand, you can configure a system interactively through the Agama Web interface or CLI, then capture the resulting configuration as a profile to reuse for future automated installations of similar systems.

The saved profile can then be loaded like any other, either with agama config load during another interactive session, or by pointing inst.auto at it for an unattended installation.

With the sections above in place, you have a working Agama profile that installs SUSE Linux Enterprise Server for SAP applications with a host name, a non-root user, and basic localization settings. Add further sections, such as storage, network, or software, as your deployment requires, or generate a starting point automatically from an interactive installation with agama config show.

An Agama installation profile uses JSON, which you can write in any text editor. Unlike XML-based AutoYaST profiles, though, JSON has no native way to reference a validation schema. Editors that support the unofficial $schema key can use it to flag invalid keys or values and suggest valid ones as you type, catching mistakes that would otherwise only surface once an unattended installation is already running. Visual Studio Code and VSCodium are the most common editors with this support.

Note: Editor-only, not used by the installer

The $schema value is used only by the editor, for validation while you write the profile. The Agama installer always validates against its own embedded schema, regardless of what $schema points to, and completely ignores this key at installation time.

A text editor that supports JSON Schema validation using the $schema key, for example Visual Studio Code or VSCodium.

Adding a $schema key to your profile gives you validation and autocompletion while editing, catching mistakes before you start an unattended installation. Remove or ignore this key when you actually run the installation; the installer does not use it.

If the installer reports that your profile is invalid even though your editor did not flag any problems, run agama config validate against the file directly to see the exact validation error the installer would report.

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": "PRODUCT_ID",
  "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 host name. The static host name is persistent across reboots, while the transient host name 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.

Note: Root or a first user is required

For the installation to succeed, either a password or an SSH public key must be set for root, or a first user (see Section 5.4, “User configuration for an Agama installation profile”) must be defined. Otherwise there is no way to log in to the installed system.

"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 an optional SSH public key.

"user": {
  "hashedPassword": false,
  "fullName": "FULL_NAME",
  "userName": "LOGIN_NAME",
  "password": "USER_PASSWORD",
  "sshPublicKey": "SSH_PUBLIC_KEY"
}

This section contains the following fields:

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

Note: Replaces the deprecated localization section

Older profiles may use a localization section instead, with language and keyboard fields. Agama's profile schema still accepts it, but marks it deprecated; use l10n in new profiles.

"l10n": {
  "locale": "LOCALE_ID",
  "keymap": "KEYMAP_ID",
  "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 SUSE Package Hub repository

When enabling SUSE Package Hub during a manual installation, you are prompted to trust the repository's GPG key. To trust it automatically during an unattended installation, add a software.import_gpg answer to the questions section. The example below uses SUSE Package Hub's current signing key; if it has since changed, get the current ID and fingerprint from a prior interactive installation or from SUSE Package Hub's repository metadata:

{
  "product": {
    "id": "SLES",
    "registrationCode": "SLES_REGISTRATION_CODE",
    "addons": [
      { "id": "PackageHub" }
    ]
  },
  "questions": {
    "policy": "auto",
    "answers": [
      {
        "class": "software.import_gpg",
        "answer": "Trust",
        "data": {
          "id": "488C583D287A0027",
          "fingerprint": "BF3F 9A67 D3A2 FF98 A73F 5E07 488C 583D 287A 0027"
        }
      }
    ]
  }
}

The storage section defines the system's target disk layout, such as devices, partitions and volume management, to be applied during installation. Its contents are defined by a separate Agama storage schema, which the profile schema references.

Note: Advanced storage configuration

An exhaustive description of all possible storage configurations using Agama is beyond the scope of this section, as it will need careful consideration of the storage model schema. For information on advanced storage configuration, refer to Section 6, “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 set up 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 on the system, because Agama cannot create that kind of device.

If the storage section is omitted entirely, Agama still needs a target for installation, so it generates an initial proposal automatically. It attempts to install onto a single disk, wiping its content and applying the product's default settings, such as Btrfs snapshots and default file system sizes. If that attempt does not produce a valid storage setup and the system has more than one disk, Agama retries the same approach on another disk, up to five attempts across as many different disks.

Note: Compatibility with legacy AutoYaST storage

In some cases, storage can be replaced by the legacyAutoyastStorage section. This section supports everything offered in the partitioning section of the AutoYaST profile. However, Agama does not validate this special section, so 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 boot loader configuration, whether that is GRUB 2 or, as a preview feature, systemd-boot (see Section 10.5, “Advanced and diagnostic options”).

"bootloader": {
  "timeout": 5,
  "extraKernelParams": "KERNEL_PARAMETERS"
}

This section contains the following fields:

Note: stopOnBootMenu and timeout are mutually exclusive

Set at most one of stopOnBootMenu and timeout in the same profile. Setting both at once fails schema validation.

The network section defines a list of network connections to be configured, using the same connection concept as NetworkManager. Each connection supports a common set of fields plus, depending on the connection type, an additional wireless, bridge, bond, or vlan section.

"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": {
        "eap": ["peap"],
        "identity": "USERNAME",
        "password": "PASSWORD",
        "caCert": "/etc/certs/ca.pem"
      }
    }
  ]
}

The following fields are common to any connection type:

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 supports the following keys:

{
  "name": "enable-apache2.sh",
  "chroot": true,
  "content": "#!/bin/bash\nsystemctl enable apache2.service"
}

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 a storage area network (SAN) or use iSCSI-based storage volumes.

The iscsi section corresponds to the Agama storage schema and contains only two properties: initiator and targets.

"iscsi": {
  "initiator": "iqn.2013-02.de.suse:01:e229358d2dea", 1
  "targets": [
    {
      "address": "TARGET_IP",
      "port": 3260,
      "name": "IQN_OF_TARGET",
      "interface": "default",
      "startup": "onboot",
      "authByTarget": {
        "username": "CHAP_USERNAME",
        "password": "CHAP_PASSWORD"
      }
    }
  ]
}

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", 1
      "state": "active",
      "format": true
    },
    {
      "channel": "0.0.5678",
      "state": "offline"
    }
  ]
}

This section defines the following keys:

The zfcp section activates zFCP (Fibre Channel Protocol) storage on IBM Z (s390x) systems for use as installation targets. There are two ways to activate zFCP storage. If your storage server supports LUN masking, activating the controller alone triggers an automatic LUN scan. Otherwise, you must define each disk manually using its hardware coordinates.

"zfcp": {
  "controllers": ["0.0.fa00", "0.0.fc00"],
  "devices": [
    {
      "channel": "0.0.fa00",
      "wwpn": "0x500507630300c562",
      "lun": "0x4010403300000000" 1
    },
    {
      "channel": "0.0.fb00",
      "wwpn": "0x500507630300c563",
      "lun": "0x4010403300000000",
      "active": false
    }
  ]
}

This section contains the following fields:

Warning: Unknown LUNs could fail to activate

If a LUN that is not already known to the system—common with storage from vendors other than IBM DS8000—fails to activate when listed under devices, activate it manually before installation instead. For example, use the rd.zdev boot parameter, or run chzdev and then rescan the devices.

Having the correct date and time during installation matters: an incorrect clock can cause unexpected errors. The Agama installation medium ships chrony, which synchronizes the system clock automatically. The optional ntp section lets you force Agama to synchronize using specific NTP sources instead, and copies that configuration to the installed system.

"ntp": {
  "sources": [
    {
      "type": "pool",
      "address": "2.opensuse.pool.ntp.org",
      "iburst": true,
      "offline": false
    }
  ]
}

The sources list defines the systems to synchronize with. Each source supports the following fields:

Note: Synchronizing time before Agama starts

If you need to synchronize the date and time before Agama itself starts (for example, if the system has no working clock), use the rd.ntp boot option instead of the profile's ntp section.

The access section configures how the installed system can be accessed remotely, over SSH and Cockpit.

"access": {
  "ssh": "enabled",
  "webConsole": "default"
}

This section contains the following fields:

The questions section automates the answers to questions the installer would otherwise ask interactively, so an unattended installation does not stall waiting for a response.

"questions": {
  "policy": "auto",
  "answers": [
    {
      "class": "storage.activate_multipath",
      "answer": "yes"
    },
    {
      "class": "storage.luks_activation",
      "answer": "decrypt",
      "password": "LUKS_PASSWORD",
      "data": {
        "device": "/dev/sda22"
      }
    }
  ]
}

The policy field determines the default behavior for questions that have no matching predefined answer:

Each entry in the answers list can contain the following fields:

Warning: Avoid the Retry answer unless certain

Using Retry as an answer can send the installation into an infinite loop if the retried action is never going to succeed. Only use it when you are certain the question will eventually succeed.

The following question classes are currently available:

This section builds on the storage section introduced in Section 5.7, “Storage configuration for an Agama installation profile”, going into more detail on how to describe devices, match existing hardware, size volumes, and control booting.

Before running an installation, validate the configuration 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 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:

{
  "name": "...",
  "search": { ... },
  "extentSize": ...,
  "physicalVolumes": [ ... ],
  "logicalVolumes": [ ... ]
}

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": "...",
  "parity": ...,
  "chunkSize": ... ,
  "devices": [ ... ],
  "size": { ... },
  "encryption": { ... },
  "filesystem": { ... },
  "partitions": [ ... ],
  "ptableType": "...",
}

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 search in the drives section considers all disks in the system, while the search in the partitions subsection only considers the partitions of the disks matched by the outer search. 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 you to match all the devices from the current context, if any. This is especially 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" } }

Besides matching by name, size, or partition number, a search section's condition also accepts the following conditions. Which ones are available depends on the kind of device:

Combine conditions with and, or, and not operators, each taking one or more nested conditions:

{
  "search": {
    "condition": {
      "and": [
        { "boss": false },
        { "size": { "greater": "100 GiB" } }
      ]
    }
  }
}

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 assume 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. For the use of current and how it affects resizing the corresponding devices, see Section 6.9, “Deleting and shrinking existing devices”.

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 is not 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 the 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 entry filesystem contains a reuseIfPossible 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.

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. The following examples match existing partitions by their file system label (set beforehand with a tool such as e2label or during a prior installation), using the filesystem search condition's label field.

"storage": {
  "drives": [
    {
      "partitions": [
        {
          "search": {
            "condition": { "filesystem": { "label": "shrinkIfNeeded" } }
          },
          "size": { "min": 0, "max": "current" }
        },
        {
          "search": {
            "condition": { "filesystem": { "label": "resizeToFixedSize" } }
          },
          "size": "15 GiB"
        },
        {
          "search": {
            "condition": { "filesystem": { "label": "resizeByRange" } }
          },
          "size": { "min": "10 GiB", "max": "50 GiB" }
        },
        {
          "search": {
            "condition": { "filesystem": { "label": "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, such as the partitions to create by default and the file systems that are supported for each of them. 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" }
            }
          }
        }
      ]
    }
  ]
}

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 Server for SAP applications. 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, all the different ways of forced and conditional activation of multipath are available to you.

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.

In a manual installation, activate multipath in one of two ways. Add the LIBSTORAGE_MULTIPATH_AUTOSTART=1 boot parameter, or confirm multipath activation in the Agama Web or command-line interface during the installation.

In an unattended installation, edit the Agama profile to include an answer to the multipath activation question. Then 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 or more of the following troubleshooting tips:

Kdump is not installed or enabled on a freshly installed system by default. A crash during or shortly after first boot would then leave you without diagnostic information. A post-installation script in your Agama profile can close that gap: it installs and enables Kdump inside the target system's chroot, before the system boots for the first time.

An Agama installation profile you control, for an unattended installation of SUSE Linux Enterprise Server for SAP applications.

With the enable-kdump post-installation script in place, Kdump is installed, enabled, and configured on the boot loader as soon as the installed system boots for the first time.

After the system completes installation and reboots for the first time, verify that Kdump is enabled and configured correctly.

Warning: Do not trigger a test crash on a production system

To confirm Kdump actually captures a crash dump, you can intentionally trigger a kernel crash with the command below, then check the /var/crash directory after the system reboots. Only do this on a non-production, disposable system.

> echo c | sudo tee /proc/sysrq-trigger

An unattended Agama installation starts from the inst.auto kernel boot parameter, or from a profile at one of Agama's predefined locations if that parameter is not given. If you also need shell access during the installation, switch to the root shell already running on virtual console 8, or set a root password with live.password to log in through a different text console or via SSH. Either way, the Agama CLI lets you load, edit, and validate the profile, then start, monitor, and finish the installation.

Agama provides a few options that ease the transition from linuxrc, the boot-time parameter parser used by earlier SUSE installers. They are not identical and work slightly differently, but should be sufficient for regular use. Unlike linuxrc, Agama is case-sensitive and requires the exact parameter name, without the additional dots, dashes, and underscores linuxrc tolerated.

Agama supports the following standard schemes (relying on curl, so a protocol may occasionally work "by accident"; only the schemes documented here are actually supported):

Agama also supports the following Agama-specific schemes, described in detail below: Section 11.3.1, “device”, Section 11.3.2, “usb”, Section 11.3.3, “label”, and Section 11.3.4, “cd, dvd, and hd”.

For the url property in the scripts and files sections of an Agama profile, the value can be a relative reference, resolved against the URL of the profile that contains it. This replaces the relurl scheme used in AutoYaST.

For example, if the profile below is retrieved from https://example.com/machines/sles16.jsonnet, the script URL resolves to https://example.com/machines/scripts/snapshot.sh:

{
  scripts: {
    postPartitioning: [
      {
        name: "snapshot",
        url: "scripts/snapshot.sh"
      }
    ]
  }
}

Standard protocols cover most use cases, but Agama-specific schemes can be handy in others. For example, you could distribute a profile on a USB stick instead of over HTTP, with usb:///profile.json, and let Agama search all attached USB devices for it.

device://sda1/profile.json

device://sda1/profiles/sles.json

device:///cciss/c1d0p5/sles.json

usb:///profile/sles.json

label://OEMDRV/sles.json

11.3.4 cd, dvd, and hd #

 

Another particular case of device://, with a slightly different form and no difference in behavior between the three names: dvd:/PATH?devices=DEVICE.

hd:/sles.jsonnet?devices=/dev/sr0
dvd:/autoinst.xml?devices=sr1

Note: Prefer device

Since cd, dvd, and hd offer no advantage over device, prefer device instead.

Agama installation logs are what you need to diagnose why an unattended installation failed or behaved unexpectedly. An unattended installation typically runs without an interactive graphical session, so the command-line workflow described here is usually the most practical way to get hold of them.

The installation itself runs from a RAM disk, so any logs you collect there are lost once the live session ends or the system boots into the newly installed system. Always copy collected logs to a permanent location before that happens.

When you actually run the collection procedure below depends on how the installation went:

Run the following procedure from a shell on the machine running the installation.

If the installation succeeded and you can boot into and log in to the newly installed system, the Agama installation logs are already preserved at /var/log/agama-installation. No separate collection step is needed.

Use agama logs store to collect a compressed archive of the installation logs, then copy that archive off the machine before the live session ends. For a system that finished installing successfully, the logs are already preserved at /var/log/agama-installation on the installed system.

agama [OPTIONS] <COMMAND>

These options apply to the agama command itself, before any subcommand:

Inspect or change the installation settings. The show subcommand generates a profile, a JSON document describing the current configuration. To change a configuration value, load a profile (complete or partial) using the load subcommand.

agama config <COMMAND>

Analyze the system. In Agama terminology, probing means analyzing the system: reading software repositories, analyzing storage devices, and more. This command starts that analysis and returns immediately.

agama probe

Start the system installation.

Warning: Destructive operation

This command sets up the storage devices, installs packages, and so on. When the preconditions for installation are not met, it informs you and returns without making any changes to the system.

agama install

Handle installer questions. Agama might require user intervention at any time; for example, it might ask you to supply missing information such as a password to decrypt a file system, or to decide what to do after an error such as a repository connection failure. This command answers such questions directly from the command line.

agama questions <COMMAND>

Collect the installer logs. The logs are stored in a compressed archive for further inspection, and include system and Agama-specific logs and configuration files that are useful for troubleshooting and debugging.

agama logs <COMMAND>

Authenticate with Agama's server. Unless you run this program as root, you need to authenticate for most operations. Log in by specifying the root password through agama auth login; on success, the server returns a JSON Web Token (JWT) that is stored and used to authenticate subsequent requests. If you run this program locally as root, authentication is skipped automatically because it uses the master token at /run/agama/token (accessible only to root).

agama auth <COMMAND>

Download a file from a given AutoYaST URL. Useful for fetching additional scripts, configuration files, or Agama auto-installation profiles using AutoYaST-supported schemes (for example, device://). To convert an AutoYaST profile instead, use agama config generate.

agama download <URL> <DESTINATION>

Finish the installation.

agama finish [METHOD]

Continuously monitor the Agama service until it finishes.

agama monitor

When run from a terminal, agama monitor shows an interactive display and lets you answer a pending installer question directly, without preparing a separate answers file. This is the preferred way to answer a question that has already come up during installation; to answer a question before it is asked, predefine the answer in the profile's questions section instead (see Section 5.19, “Questions configuration for an Agama installation profile”). When standard output is not a terminal, agama monitor falls back to plain text output.

Print the current state of the installation (for example, waiting, blocked, running, or finished).

agama status [OPTIONS]

Display Agama events.

agama events [OPTIONS]