Skip to content

Add documentation forscripts.retry questions #134

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
imobachgs wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add documentation forscripts.retry questions #134

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7825f33
Improve answers.md format using prettier
imobachgs Dec 9, 2025
748b631
Document the scripts.retry question
imobachgs Dec 9, 2025
8058ce1
Rename "answers.md" to "questions.md"
imobachgs Dec 9, 2025
9e82eac
Remove the `stdout` key in the scripts.retry questions
imobachgs Dec 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/user/guides/multipath.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ For that, a JSON configuration containing the following settings must be loaded.
}
```

Read [the profile format reference](../reference/profile/answers) for more info about specifying
Read [the profile format reference](../reference/profile/questions) for more info about specifying
answers at the Agama configuration.

Also check the starter's guide if you need any clarification regarding how to load an Agama
Expand Down
113 changes: 0 additions & 113 deletions docs/user/reference/profile/answers.md
View file
Open in desktop

This file was deleted.

114 changes: 114 additions & 0 deletions docs/user/reference/profile/questions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
---
sidebar_position: 15
---

# Questions

Agama allows you to automate the process of answering questions during an unattended installation.
This feature is crucial for creating truly hands-off Agama profiles, as it eliminates the need for
user interaction when the installer encounters a choice or requires specific input.

This section explains how to define policies for answering questions and provides a list of the
question classes you can configure.

---

## Configuring automatic answers

Automatic answers are configured within the `questions` key of your Agama profile. This object has
two main properties: `policy` and `answers`.

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

## The `policy` property

The `policy` property determines the default behavior for questions the installer encounters. It's a
string with two possible values:

- **`"user"`** (default): The installer will use any pre-defined answers from the `answers` list. If
a question is encountered that does not have a matching answer, the installer will ask the user
for a response.
- **`"auto"`**: The installer will use any pre-defined answers from the `answers` list. If a
question is encountered that does not have a matching answer, the installer will automatically
select the default value for that question. If there's no default, the installation will fail.

## The `answers` property

The `answers` property is an array of objects, where each object represents a pre-defined answer for
a specific question.

Each answer object can have the following properties:

- `class`: a unique identifier for the question (e.g., `"storage.activate_multipath"`).
- `text`: the full text of the question.
- `answer`: the value to be used as the answer.
- `password`: an additional field that is required for questions that also need a password, such as
`storage.luks_activation` with `decrypt` answer.
- `data`: an optional object with additional key-value pairs to match the question.

The installer will attempt to match a question to an answer by checking the `class`, `text`, and
`data` properties.

:::note Partial data matching

The installer performs a **partial match** on the `data` object. If your answer's `data` entry
contains a subset of the properties in the question's data, it will still be considered a match if
the values for the specified properties are identical. For example, a question might contain
`{ "id": "123", "checksum": "abc", "name": "file.txt" }`, but you only need to specify
`{ "checksum": "abc" }` to match it.

:::

:::warning

The `Retry` value for the `answer` property could get the installation into an infinity loop. Avoid
using `Retry` if you are not totally sure that the question is going to success at some point. In
the future, this problem could be overcome by defining a maximum number of attempts.

:::

---

## Supported question classes

The following table lists the possible question classes, their descriptions, and the data you can
use to match them.

| Class | Description | Possible Answers | Available Data |
| :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `autoyast.unsupported` | When there are unsupported elements in an AutoYaST profile. | `Abort`, `Continue` | `planned`: elements to be supported in the future.<br />`unsupported`: unsupported elements. |
| `scripts.retry` | When a user script fails | `yes`, `no` | `name`: script's name.<br />`stderr`: standard error (limited to 512 bytes at most).<br />`exit_status`: exit status code. |
Copy link
Copy Markdown
Contributor

@jreidinger jreidinger Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

well, this is new type for 16.1, right? I think we really need some way how to indicate to user what works where. Also if I get code the data is not always available if script failed due to different reason than non-zero exit code. So maybe some warning that data is not available always?

| `software.medium_error` | When there is an issue accessing the software medium. | `Retry`, `Skip` | `url`: The URL where the access failed. |
| `software.unsigned_file` | When a file from a repository is not digitally signed. | `Yes`, `No` | `filename`: The name of the file. |
| `software.import_gpg` | When a signature is signed with an unknown GPG key. | `Trust`, `Skip` | `id`, `name`, `fingerprint`: Details of the unknown key. |
| `software.unknown_gpg` | When a file is signed by an unknown key. | `Trust`, `Skip` | `id`: The key ID.<br />`filename`: The name of the signed file. |
| `software.digest.no_digest` | When a file is in a signed repository, but is not listed in the list of checksums. | `Yes`, `No` | |
| `software.digest.unknown_digest` | When a file has a checksum, but the expected checksum is not known. This question type is also used for wrong checksums. | `Yes`, `No` | |
| `software.package_error.medium_error` | When a package failed to be downloaded from the medium. | `Retry`, `Continue` | `url`: The URL of the package. |
| `software.package_error.provide_error` | When a package failed to be provided, e.g., due to an IO error. | `Retry`, `Continue` | |
| `software.script_error` | When a package script failed. | `Retry`, `Continue` | `details`: The details of the failure. |
| `storage.activate_multipath` | When it looks like the system has multipath and if it should be activated. | `yes`, `no` | |
| `storage.commit_error` | When some storage actions failed and if it should continue. | `yes`, `no` | |
| `storage.luks_activation` | When a LUKS encrypted device is detected and requires a password to probe it. | `skip`, `decrypt` | `device`: The device name.<br />`label`: The device label.<br />`size`: The device size.<br />`attempt`: The number of the current attempt. |
| `load.retry` | Asks the user to retry loading the profile. | `Yes`, `No` | `error`: The text of the error message. |
| `registration.certificate` | When the registration server uses an unknown certificate. | `trust`, `reject` | `url`: The server URL.<br />`issuer_name`, `issue_date`, `expiration_date`: Certificate details.<br />`sha1_fingerprint`, `sha256_fingerprint`: Certificate fingerprints. |