Agama offers two different approaches to unattended installation. On the one hand, the user can provide a file, known as a "profile", that includes a description of the system to install. This approach might sound familiar to AutoYaST users. On the other hand, Agama can accept just a plain shell script, enabling custom pre-installation workflows.

Although Agama defines its own profile format, it is able to partially handle AutoYaST profiles. Please, check the AutoYaST support document for further information.

A profile defines which options to use during installation: which product to install, localization settings, partitioning schema, etc. Although it sounds similar to AutoYaST, there are some essential differences:

• Profiles are written in Jsonnet instead of XML. Jsonnet is a superset of JSON (so you can use just plain JSON), which allows for writing more readable and concise profiles.
• Dynamic profiles are achieved using Jsonnet itself instead of relying on rules or Embedded Ruby (ERB). Agama injects hardware information that can be processed using Jsonnet standard library.

You can check the Tumbleweed installation profile included in the repository to get an impression of how a profile looks like.

{
  "l10n": {
    "languages": ["en_US.UTF-8"]
  },
  "product": {
    "id": "Tumbleweed"
  },
  "storage": {
    "bootDevice": "/dev/sda"
  },
  "user": {
    "fullName": "Jane Doe",
    "password": "123456",
    "userName": "jane.doe"
  }
}

Check the JSON Schema to learn about the supported elements.

The profile can be adapted at runtime depending on the system where the auto-installation is running. For such use cases, Agama injects the hardware information into the profile to be processed using Jsonnet.

Please, check the example profile for further information.

Agama includes a handy command-line interface available in the agama package. Among many other things, it allows downloading, validating and evaluating profiles. For instance, we could check the result of the previous profile by running the following command:

$ sudo agama profile evaluate my-profile.jsonnet

Do you want to check whether your profile is valid? agama have you covered. Bear in mind that you can only validate JSON profiles (a Jsonnet profile must be evaluated first).

$ agama profile validate my-profile.json

Writing the profile by hand is relatively easy. However, you might want to ask Agama to do it for you. You can boot the installation, use the web interface to tweak all the values and, from the terminal, generate the file by running the following command:

$ sudo agama config show > profile.json

Instead of a profile, you can provide a shell script, having complete control of the process. In this scenario, it is expected to use the CLI to interact with Agama. In addition, you can rely on any other tool available in the installation media. What's more, when using the Live ISO, you could install your own tools.

Below there is a minimal working example to install Tumbleweed:

set -ex

/usr/bin/agama profile import ftp:https://my.server/profile.json
/usr/bin/agama install

You might want to have a look to Agama's default script for inspiration. Such a script comes into action when you provide a profile.

The goal of this section is to document examples and use cases for additional scripting support in Agama auto-installation.

In some cases it is necessary to activate tricky devices manually before starting the installation. An example is when you have two network cards, one for the external network and the other for the internal network.

set -ex

/usr/bin/agama download ftp:https://my.server/tricky_hardware_setup.sh > tricky_hardware_setup.sh
sh tricky_hardware_setup.sh
/usr/bin/agama profile import ftp:https://my.server/profile.json
/usr/bin/agama install

Jsonnet may be unable to handle all of the profile changes that users wish to make.

set -ex

/usr/bin/agama download ftp:https://my.server/profile.json > /root/profile.json

# modify profile.json here

/usr/bin/agama profile import file:https:///root/profile.json
/usr/bin/agama install

Note: currently not supported (params to install is not implemented yet).

Sometimes there is a more complex partitioning that needs to be modified after partitioning done by Agama and before installing RPMs, such as changing the fstab and mount an extra partition.

set -ex

/usr/bin/agama profile import https://my.server/profile.json
/usr/bin/agama install --until partitioning # install till the partitioning step

# Place for specific changes to /dev

/usr/bin/agama install # do the rest of the installation

Note: not supported now (params to install is not implemented yet).

If there is a need to modify the system before rebooting, e.g. to install mandatory security software for internal network, then it must be modified before umount.

set -ex

/usr/bin/agama download ftp:https://my.server/velociraptor.config
/usr/bin/agama profile import https://my.server/profile.json
/usr/bin/agama install --until deploy # do partitioning, rpm installation and configuration step

# Example of enabling velociraptor

zypper --root /mnt install velociraptor-client

mkdir -p /mnt/etc/velociraptor
cp velociraptor.config /mnt/etc/velociraptor/client.config

systemctl --root /mnt enable velociraptor-client

/usr/bin/agama install # do the rest of the installation - basically unmount and copy logs

Another scenario is when you need to make some changes required for a successful reboot, such as some kernel tuning or adding some remote storage that needs to be mounted during boot.

set -ex

/usr/bin/agama profile import https://my.server/profile.json
/usr/bin/agama install --until deploy # do partitioning, rpm installation and configuration step

# Do custom modification of /mnt including call to dracut

/usr/bin/agama install # do the rest of the installation - basically unmount and copy logs

Users usually do a lot of things with post installation scripts in AutoYaST e.g. calling zypper to install additional software, modify configuration files or manipulate with systemd services. This is done after the first reboot. If this is the case, Agama will simply delegate it to any other tool the user prefers for initial configuration, such as ignition/combustion.

The auto-installation is started by passing agama.auto=<url> on the kernel's command line. If you are using the Live media, you need to edit the Grub2 entry to add that option. Or you can use PXE if it fits better. For instance, agama.auto=https://example.net/bedrock.jsonnet.

Using the correct extension in the file name is important:

• .jsonnet enables dynamic content through Jsonnet.
• .json assumes the profile is just a JSON file, so no dynamic content is expected.
• .xml, .erb or a trailing slash (/) indicates that you want to import an AutoYaST profile. Check the AutoYaST support document for further information.
• .sh would be interpreted as a shell script.

Auto-installation support is far from being complete, so you should have a few things into account:

• Progress reporting through the command-line interface is limited, so you should watch the web interface, especially if the installation gets stuck.
• If something goes wrong processing the profile, you will not notice because Agama does not report such problems yet. The only consequence is that the installation will not start. You can check the output of journalctl -u agama-auto for further information.
• You need to manually reboot the system after installation.