agama-project · imobachgs · Feb 19, 2025 · Feb 17, 2025 · Feb 17, 2025 · Feb 17, 2025
diff --git a/docs/user/autoyast.md b/docs/user/autoyast.md
diff --git a/docs/user/autoyast/index.md b/docs/user/autoyast/index.md
@@ -0,0 +1,18 @@
+# AutoYaST support
+
+We know that many AutoYaST users have invested quite some time in writing their profiles to perform
+unattended installations. For that reason, Agama offers a mechanism to reuse such profiles to some extent.
+
+However, Agama and AutoYaST have different features. Unlike AutoYaST, Agama is focused on the
+installation and delegates further configuration to other tools. From this point of view, it is
+clear that many of the sections in an AutoYaST profile will not have an Agama counterpart.
+
+This document describes how AutoYaST supports work, including the limitations you might find.
+
+:::warning
+AutoYaST support is not fully defined yet, which means that we might add support for more sections
+in the future even if we do not plan to do so now. However, we will do our best to keep this
+document up to date.
+
+Please, let us know if you miss support for any section.
+:::
diff --git a/docs/user/autoyast/profiles.md b/docs/user/autoyast/profiles.md
@@ -0,0 +1,30 @@
+# Loading an AutoYaST profile
+
+The typical way of starting an unattended installation in Agama is by passing the URL of an AutoYaST
+profile through the [`agama.auto`](../boot_options.md#boot-options) argument in the kernel's
+command-line[^agama-profile-import]. For example:
+
+```text
+agama.auto=http://example.net/agama/tumbleweed.xml
+```
+
+Agama takes care of pre-processing and converting the profile to an Agama equivalent. As part of
+this pre-processing, it supports handling of [dynamic profiles][dynamic-profiles], including:
+
+- [Rules and classes][rules-classes].
+- [Embedded Ruby (ERB)][erb].
+- [Pre-installation scripts][pre-scripts].
+- [Ask lists][ask-lists] (not implemented yet). Note for developers: fortunately, the code to
+  [parse][ask-list-reader] and [run][ask-list-runner] the process is there but we need to adapt the
+  [user interface][ask-list-dialog], which is not trivial.
+
+[dynamic-profiles]: https://doc.opensuse.org/documentation/leap/autoyast/html/book-autoyast/part-dynamic-profiles.html
+[rules-classes]: https://doc.opensuse.org/documentation/leap/autoyast/html/book-autoyast/rulesandclass.html
+[erb]: https://doc.opensuse.org/documentation/leap/autoyast/html/book-autoyast/erb-templates.html
+[pre-scripts]: https://doc.opensuse.org/documentation/leap/autoyast/html/book-autoyast/cha-configuration-installation-options.html#pre-install-scripts
+[ask-lists]: https://doc.opensuse.org/documentation/leap/autoyast/html/book-autoyast/cha-configuration-installation-options.html#CreateProfile-Ask
+[ask-list-reader]: https://github.com/yast/yast-autoinstallation/blob/c2dc34560df4ba890688a0c84caec94cc2718f14/src/lib/autoinstall/ask/profile_reader.rb#L29
+[ask-list-runner]: https://github.com/yast/yast-autoinstallation/blob/c2dc34560df4ba890688a0c84caec94cc2718f14/src/lib/autoinstall/ask/runner.rb#L50
+[ask-list-dialog]: https://github.com/yast/yast-autoinstallation/blob/c2dc34560df4ba890688a0c84caec94cc2718f14/src/lib/autoinstall/ask/dialog.rb#L23
+
+[^agama-profile-import]: You can use the `agama profile import` command, but that's out of the scope of this document.
diff --git a/docs/user/autoyast/reference.md b/docs/user/autoyast/reference.md
diff --git a/docs/user/unattended/scripts.md b/docs/user/unattended/scripts.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 # Running scripts
@@ -13,7 +13,7 @@ Agama allows execute scripts at the following points of the installation process
 This section describes how to specify a script and goes through some use-cases.
 
 :::note
-You can compare Agama scripts to the AutoYaST ones in the [Scripts section](../autoyast.md#scripts)
+You can compare Agama scripts to the AutoYaST ones in the [scripts section](../autoyast/reference.md#scripts)
 of the backward compatibility documentation.
 :::
 
@@ -92,6 +92,12 @@ Jsonnet to build a dynamic profile. If you need something that behaves exactly l
 still use an AutoYaST profile with its own pre-scripts section.
 :::
 
+## Post-partitioning scripts
+
+The post-partitioning scripts are executed during the installation, after the storage is
+set up. A typical use case is to create configuration files that can modify the behavior of
+the RPM scripts.
+
 ## Post-installation scripts
 
 The post-installation scripts are executed after the system is installed. They are helpful for

diff --git a/docs/user/unattended/storage.md b/docs/user/unattended/storage.md
@@ -21,7 +21,7 @@ section `legacyAutoyastStorage`, which is a 1:1 representation of the XML AutoYa
 section supports everything offered by the `partitioning` AutoYaST section. Note that Agama does not
 validate this special section, so be careful to provide valid AutoYaST options.
 
-~~~json
+```json
 {
   "legacyAutoyastStorage": [
     {
@@ -30,7 +30,7 @@ validate this special section, so be careful to provide valid AutoYaST options.
     }
   ]
 }
-~~~
+```
 
 Although that special section is offered for backwards compatibility and to ease gradual migration
 from AutoYaST to Agama, there are no plans to introduce any improvement or new feature in that
@@ -355,11 +355,11 @@ drive, it will be considered to contain the following one.
 
 ```json
 {
-    "search": {
-        "sort": { "property": "name" },
-        "max": 1,
-        "ifNotFound": "error"
-    }
+  "search": {
+    "sort": { "property": "name" },
+    "max": 1,
+    "ifNotFound": "error"
+  }
 }
 ```
 
@@ -490,18 +490,18 @@ ranges for its relevant file systems like "/", "swap", "/home", etc.
 On the other hand, the size limits of some devices can be omitted if they can be inferred from other
 related devices following some rules.
 
- - For an MD RAID defined on top of new partitions, it is possible to specify the size of all the
-   partitions that will become members of the RAID but is also possible to specify the desired size
-   for the resulting MD RAID and then the size limits of each partition will be automatically
-   inferred with a small margin of error of a few MiBs.
- - Something similar happens with a partition that acts as the **only** physical volume of a new LVM
-   volume group. Specifying the sizes of the logical volumes could be enough, the size limits of the
-   underlying partition will match the necessary values to make the logical volumes fit. In this
-   case the calculated partition size is fully accurate.
- - The two previous scenarios can be combined. For a new MD RAID that acts as the **only** physical
-   volume of a new LVM volume group, the sizes of the logical volumes can be used to precisely
-   determine what should be the size of the MD and, based on that, what should be the almost
-   exact size of the underlying new partitions defined to act as members of the RAID.
+- For an MD RAID defined on top of new partitions, it is possible to specify the size of all the
+  partitions that will become members of the RAID but is also possible to specify the desired size
+  for the resulting MD RAID and then the size limits of each partition will be automatically
+  inferred with a small margin of error of a few MiBs.
+- Something similar happens with a partition that acts as the **only** physical volume of a new LVM
+  volume group. Specifying the sizes of the logical volumes could be enough, the size limits of the
+  underlying partition will match the necessary values to make the logical volumes fit. In this
+  case the calculated partition size is fully accurate.
+- The two previous scenarios can be combined. For a new MD RAID that acts as the **only** physical
+  volume of a new LVM volume group, the sizes of the logical volumes can be used to precisely
+  determine what should be the size of the MD and, based on that, what should be the almost
+  exact size of the underlying new partitions defined to act as members of the RAID.
 
 The two described mechanisms to automatically determine size limits can be combined. Even creating
 a configuration with no explicit sizes at all like the following example.
@@ -576,10 +576,10 @@ A `search` section allows to match the definition of a partition or an LVM logic
 (or several) devices existing in the system. It is then possible to specify that the given
 partitions or volumes must be:
 
-  - Deleted if needed to make space for the newly defined devices
-  - Deleted in all cases
-  - Shrunk to the necessary size to make space for new devices
-  - Shrunk or extended to a given size, maybe a range
+- Deleted if needed to make space for the newly defined devices
+- Deleted in all cases
+- Shrunk to the necessary size to make space for new devices
+- Shrunk or extended to a given size, maybe a range
 
 It is even possible to express some combinations of the above, like "try to shrink it to make space
 but proceed to delete it if shrinking it is not enough".
@@ -780,7 +780,7 @@ short syntax for `generate`.
 
 Every product provides a configuration which defines the storage volumes (e.g., feasible file
 systems for root, default partitions to create, etc). The default or mandatory product volumes can
-be automatically generated by using a *generate* section in the *partitions* or *logicalVolumes*
+be automatically generated by using a _generate_ section in the _partitions_ or _logicalVolumes_
 sections.
 
 ```json
@@ -796,7 +796,7 @@ sections.
 
 ```
 
-The *generate* section allows creating the product volumes without explicitly writing all of them.
+The _generate_ section allows creating the product volumes without explicitly writing all of them.
 The config above would be equivalent to something like this:
 
 ```json
@@ -814,7 +814,7 @@ The config above would be equivalent to something like this:
 
 ```
 
-If any path is explicitly defined, then the *generate* section will not generate a volume for it.
+If any path is explicitly defined, then the _generate_ section will not generate a volume for it.
 For example, with the following config only root and swap would be automatically added:
 
 ```json
@@ -851,7 +851,7 @@ The auto-generated volumes can be also configured. For example, for encrypting t
 }
 ```
 
-The *mandatory* keyword can be used for only generating the mandatory partitions or logical volumes:
+The _mandatory_ keyword can be used for only generating the mandatory partitions or logical volumes:
 
 ```json
 "storage": {
@@ -866,7 +866,7 @@ The *mandatory* keyword can be used for only generating the mandatory partitions
 }
 ```
 
-The *default* and *mandatory* keywords can also be used to generate a set of formatted MD arrays.
+The _default_ and _mandatory_ keywords can also be used to generate a set of formatted MD arrays.
 Assuming the default volumes are "/", "/home" and "swap", the following snippet would generate three
 RAIDs of the appropriate sizes and the corresponding six partitions needed to support them.
 
@@ -916,7 +916,7 @@ of the devices to use are added to the list of physical volumes:
 ```
 
 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
+which to create the partitions. For that, a _generate_ section is added to the list of physical
 volumes:
 
 ```json
@@ -939,8 +939,7 @@ volumes:
 ```
 
 If the auto-generated physical volumes have to be encrypted, then the encryption config is added to
-the *generate* section:
-
+the _generate_ section:
 
 ```json
 "storage": {

diff --git a/docs/user/unattended/users.md b/docs/user/unattended/users.md
@@ -0,0 +1,75 @@
+---
+sidebar_position: 2
+---
+
+# Users and authentication
+
+There are two sections related to users and authentication in an Agama profile:
+
+- `root`: allows to set the authentication mechanism for the `root` user.
+- `user`: defines a "first user".
+
+For a successful installation, one of the following conditions must be met:
+
+- A password or an SSH public key is defined for the `root` user.
+- A first user is defined.
+
+## `root`
+
+The `root` section allows to specify an authentication method for the `root` user.
+
+```json
+{
+  "root": {
+    "sshPublicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPj/J1N38v/7Gbxz5A6jiSBhLbUwrJOVlBxDQhuW8tvg user@example.net",
+    "hashedPassword": true,
+    "password": "$y$j9T$qGMrxRmEHUV3kCXQAywcP1$g4n4.O2tUf2Dq9CJTohTb4/HJ9Wdzr2Z33MD8srkPV1"
+  }
+}
+```
+
+The following fields are supported:
+
+- `password`: `root` password, hashed or not depending on `hashedPassword`.
+- `hashedPassword`: whether the `password` is hashed (`true`) or not (`false` or undefined).
+- `sshPublicKey`: SSH public key to be copied to the `/root/.ssh/authorized_keys` file.
+
+## `user`
+
+The `user` section defines a first user:
+
+```json
+{
+  "user": {
+    "fullName": "Jane Doe",
+    "userName": "jane.doe",
+    "hashedPassword": false,
+    "password": "123456"
+  }
+}
+```
+
+This section includes the following fields:
+
+- `userName`: user name (or login name).
+- `fullName`: user's full name.
+- `password`: `root` password, hashed or not depending on `hashedPassword`.
+- `hashedPassword`: whether the `password` is hashed (`true`) or not (`false` or undefined).
+
+## Encrypted passwords
+
+The encrypted password can be obtained by running the `mkpasswd` command from the `whois` package.
+
+To get the list of supported hashing methods run the `mkpasswd --method=help` command. Then use the
+selected method for hashing your password, for example `mkpasswd --method=yescrypt`.
+
+Make sure the selected hashing method is supported by the target system, different systems might
+support different set of methods.
+
+:::warning
+Do not use any DES or MD5 based algorithms, these are considered insecure. Check `man 5 crypt`
+manual page for details about the hashing methods and their strength.
+:::
+
+Alternatively you can use the `openssl passwd -6` command. This generates a SHA-512 password hash,
+for the SHA-256 method use the `-5` option.