diff --git a/docs/user/autoyast.md b/docs/user/autoyast.md deleted file mode 100644 index c141a05..0000000 --- a/docs/user/autoyast.md +++ /dev/null @@ -1,529 +0,0 @@ -# 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. -::: - -## 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. - -## Supported sections - -Let's describe which sections and elements from an AutoYaST profile are (or will be) supported in -Agama. In some cases, you might find a table with the following columns: - -- AutoYaST: name of the AutoYaST element. -- Supported: whether it is (or will be) supported. The meaning of each value is: - - Yes: fully supported. - - Planned: not supported yet, but there are plans to support it. - - Undecided: no decision about whether it should be supported. - - No: there are not plans for supporting that element. -- Agama: name of the Agama element. -- Comment: any comment or reason about the element. - -### `dasd` and `iscsi-client` - -Support for iSCSI and DASD devices is missing in Agama profiles. But we definitely plan to support -them. - -### `general` - -AutoYaST `general` section contains a set of elements that, for some reason, did not find a better -place. Most of those options will be ignored by Agama (e.g., `cio_ignore`, `mode`, `proposals`, -etc.). However, we might need to add support for a handful of them. - -Agama should process the `ask-list` section (see [Supported sections](#supported-sections)), -`signature-handling` (to deal with packages signatures) and, most probably, `storage` too (e.g., -affects the proposal). - -### `groups` and `users` - -Regarding users, Agama only allows defining the first user and setting the root authentication -mechanism (password and/or SSH public key). However, AutoYaST allows to specify a list of users and -groups plus some authentication settings. We have at least two options here: - -- Extract the root authentication data from the profile and try to infer which is the first user. - This behavior is already implemented. -- Import these sections as given because they are handled by the YaST code in Agama. - -| AutoYaST | Supported | Agama | Comment | -| -------- | --------- | ----- | -------------------------------------------- | -| groups | No | | It is not planned, but we should consider | -| users | No | | It is not planned, but we should consider | -| | | root | Root user (only password and SSH public key) | -| | | user | First non-system user from "users" | - -For the first user, the following elements are supported: - -| AutoYaST | Supported | Agama | Comment | -| -------------------- | --------- | ----------------- | ---------------------- | -| authorized_keys | Planned | | Only for the root user | -| encrypted | Yes | encryptedPassword | | -| forename | No | | | -| fullname | Yes | fullName | | -| gid | No | | | -| group | No | | | -| groups | No | | | -| home | No | | | -| home_btrfs_subvolume | No | | | -| password_settings | No | | | -| shell | No | | | -| surname | No | | | -| uid | No | | | -| user_password | Yes | password | | -| username | Yes | userName | | - -#### Encrypted password - -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. - -### `keyboard` - -Only the `keymap` element is translated. The rest of options are ignored in YaST and they are not -even documented in the AutoYaST handbook. - -| AutoYaST | Supported | Agama | Comment | -| -------- | --------- | ------------- | ------------------------------ | -| keymap | Yes | l10n.keyboard | Should we rename it to keymap? | -| capslock | No | | Deprecated | -| delay | No | | Deprecated | -| discaps | No | | Deprecated | -| numlock | No | | Deprecated | -| rate | No | | Deprecated | -| scrlock | No | | Deprecated | -| tty | No | | Deprecated | - -### `language` - -| AutoYaST | Supported | Agama | Comment | -| --------- | --------- | -------------- | ------------------------- | -| language | Yes | l10n.languages | First element of the list | -| languages | Yes | l10n.languages | | - -### `networking` - -The `networking` section in AutoYaST is composed of several sections: `dns`, `interfaces`, -`net-udev`, `routing` and `s390-devices`. At this point, Agama only supports defining a list of -connections that could correspond with the AutoYaST interfaces list. We might need to extend Agama -to support `dns`, `net-udev`, etc. - -| AutoYaST | Supported | Agama | Comment | -| ----------------------- | --------- | ----------- | ---------------------------------- | -| backend | No | | No plan for additional backends | -| dhcp_options | No | | | -| dns | Partial | | Included in connections | -| interfaces | Partial | connections | Check the connections table below | -| ipv6 | Yes | | It affects `method4` and `method6` | -| keep_install_network | No | | | -| managed | No | | | -| modules | No | | | -| net-udev | No | | | -| routing | Planned | | | -| s390-devices | Planned | | | -| setup_before_proposal | No | | | -| strict_IP_check_timeout | No | | | -| virt_brige_proposal | No | | | - -As seen in the table above, AutoYaST `interfaces` corresponds with Agama `connections`, but the -format is not exactly the same. - -| AutoYaST | Supported | Agama | Comment | -| -------------------------- | --------- | ----------- | --------------------------------------- | -| device | Yes | interface | | -| name | Yes | id | | -| description | No | | | -| bootproto | Partial | method{4,6} | Different set of values | -| startmode | No | | Do not set up connections you won't use | -| lladdr | Yes | macAddress | | -| ifplugd_priority | No | | Not relevant (no ifplugd support) | -| usercontrol | No | | | -| dhclient_set_hostname | No | | | -| ipaddr | Yes | addresses | | -| prefixlen | Yes | addresses | Part of `addresses` | -| remote_ipaddr | Undecided | | | -| netmask | Yes | addresses | Part of `addresses` | -| bonding\_\* | Yes | bond | Use a different format to define bonds | -| aliases | Yes | | Part of `addresses` | -| broadcast | No | | Part of `addresses` | -| network | No | | Part of `addresses` | -| mtu | Undecided | | | -| ethtool_options | Undecided | | | -| wireless | Yes | wireless | It uses a different format | -| wifi_settings | Partial | wireless | It uses a different format | -| bridge_settings | Planned | | | -| vlan_settings | Planned | | | -| dhclient_set_down_link | No | | | -| dhclient_set_default_route | No | | | -| zone | No | | | -| firewall | No | | | - -#### Wireless connections - -Setting up a wireless connection in AutoYaST is not even documented, although it is possible. In -Agama, the options are placed under a `wireless` key. - -| AutoYaST | Supported | Agama | Comment | -| ---------------------------- | --------- | -------- | ----------------------- | -| wireless_auth_mode | Partial | security | Different set of values | -| wireless_ap | Undecided | | | -| wireless_bitrate | Undecided | | | -| wireless_ca_cert | Undecided | | | -| wireless_channel | Undecided | | | -| wireless_client_cert | Undecided | | | -| wireless_client_key | Undecided | | | -| wireless_client_key_password | Undecided | | | -| wireless_default_key | Undecided | | | -| wireless_eap_auth | Undecided | | | -| wireless_eap_mode | Undecided | | | -| wireless_essid | Yes | ssid | | -| wireless_frequency | Undecided | | | -| wireless_key | Undecided | | | -| wireless_key_0 | Undecided | | | -| wireless_key_1 | Undecided | | | -| wireless_key_2 | Undecided | | | -| wireless_key_3 | Undecided | | | -| wireless_key_length | Undecided | | | -| wireless_mode | Partial | mode | Different set of values | -| wireless_nick | No | | | -| wireless_nwid | No | | | -| wireless_peap_version | No | | | -| wireless_power | No | | | -| wireless_wpa_anonid | No | | | -| wireless_wpa_identity | No | | | -| wireless_wpa_password | Yes | password | | -| wireless_wpa_psk | Yes | password | | - -#### Bonding connections - -The AutoYaST `bonding*` elements allow setting up a bonding interface. In Agama, those settings are -placed under a `bond` key in the `connection` structure. - -| AutoYaST | Supported | Agama | Comment | -| ------------------- | --------- | ------- | ----------------------------- | -| bonding_master | Yes | | The master defines the `bond` | -| bonding_slaveX | Yes | ports | | -| bonding_module_opts | Yes | options | | -| - | | mode | Specific key to set the mode | - -Agama includes an specific `mode` options to set the mode, instead of abusing the -`bonding_module_opts`. - -#### Bridge connections - -:::warning -Bridge support is not implemented yet although we have support at model level. -::: - -The AutoYaST `bridge*` elements allow setting up a bridge. In Agama, those settings are placed under -a `bridge` key in the `connection` structure. - -| AutoYaST | Supported | Agama | Comment | -| -------------------- | --------- | ------------- | --------------------------------------- | -| bridge | Planned | | An existing `bridge` key means the same | -| bridge_ports | Planned | ports | | -| bridge_stp | Planned | stp | | -| bridge_forward_delay | Planned | forward_delay | | -| bridge_forwarddelay | Planned | forward_delay | Compatibility bsc#1180944 | - -#### VLAN - -:::warning -VLAN support is not implemented yet although we have support at model level. -::: - -The AutoYaST `vlan_settings` elements allow setting up a bridge. In Agama, those settings are placed -under a `vlan` key in the `connection` structure. - -| AutoYaST | Supported | Agama | Comment | -| ----------- | --------- | -------- | ------- | -| vlan_id | Planned | id | | -| etherdevice | Planned | parent | | -| - | Planned | protocol | | - -### `partitioning` - -By far, the most complex part of an AutoYaST profile. We can import the AutoYaST `partitioning` -section as it is because the partitioning is handled by the same code in Agama and AutoYaST. - -However, we must implement a mechanism to convert to/from both profile types. - -### `proxy` - -To use a proxy in Agama, you set the `proxy` in the [kernel's command line][cmdline]. In AutoYaST, -you can specify the proxy in the profile apart from the command line. - -Although we need to support the same use case, we should avoid introducing a `proxy` section unless -it is strictly required. - -[cmdline]: https://github.com/openSUSE/agama/blob/a105391949a914ae57719c80a610c642fb581924/service/lib/agama/proxy_setup.rb#L31 - -### `report` - -The AutoYaST `report` section defines which kind of messages to report (errors, warnings, -information and yes/no messages) and whether the installation should stop on any of them. Agama does -not have an equivalent mechanism. Moreover, it is arguable whether it is a good idea to base on the -type of message to stop the installation. A more fine-grained control over the situations that -should stop the installation would be better. As an example, consider the `signature-handling` -section. - -### `scripts` - -AutoYaST implements five kind of scripts: `pre`, `post-partitioning`, `chroot`, `post`, and `init`. -In Agama there are only three of them, although the original `pre-scripts` behavior is preserved -when importing an AutoYaST profile. - -The following table summarizes the equivalences: - -| AutoYaST | When they run | Agama equivalent | -| ----------------- | ------------------------------- | ------------------------------------ | -| pre | before the installation starts | pre, see [Pre-scripts](#pre-scripts) | -| post-partitioning | after the partitioning is done | none | -| chroot | after the installation finishes | post | -| post | before the 2nd stage | none, as there is no 2nd stage | -| init | at the end of the 1st boot | init | - -The pre-scripts are processed by AutoYaST code itself, and the `post` and `init` scripts are merged -into a single type (`init`) which runs during the 1st boot after the installation. - -#### Scripts representation - -A definition of an AutoYaST script supports several features. However, in Agama we are implementing -only those we consider essential. - -| AutoYaST | Supported | Agama | Comment | -| ------------- | --------- | ------ | --------------------- | -| file_name | Yes | name | | -| location | Yes | url | | -| source | Yes | body | | -| rerun | No | | | -| interpreter | Partial | | Script's shebang | -| feedback | No | | | -| feedback_type | No | | | -| debug | No | | | -| notification | No | | | -| param-list | Planned | | | -| chrooted | Yes | chroot | Only for post-scripts | - -#### pre-scripts - -AutoYaST pre-scripts are executed before the installation and are a powerful method to customize the -profile at runtime. If you are using an AutoYaST profile, `pre-scripts` will work in the same way -with Agama. Please, check the [Dynamic profiles][dynamic-profiles] section for further details. - -However, Agama ships its own pre-scripts mechanism, although they do not allow modifying the profile -itself because using [Jsonnet](https://jsonnet.org/) is the preferred way to do that. The main use -cases for Agama pre-scripts are activating hardware, tweaking the installation media, etc. - -:::note -We might consider adding support to modify the profile using a pre-script directly in Agama. -::: - -#### post-partitioning scripts - -AutoYaST post-partitioning scripts are executed after the partitioning is done and before the -software installation starts. Agama does not implement a similar mechanism because we failed to find -a use case for it. - -#### chroot-scripts - -`chroot-scripts` allows running scripts at the end of the installation and before the system is -rebooted. Agama's counterpart are `post-scripts`. Both methods allow running the scripts on the -installation media or in the target system, using a `chroot`. - -#### post-scripts and init-scripts - -AutoYaST allows running scripts after the first boot of the system, during and after the so-called -2nd stage. Agama is not present into the installed system, thus it does not implements a 2nd stage. -However, it supports defining a set of `init` scripts. If required, Agama installs a systemd service -that takes care of running those scripts during the 1st boot. - -It is worth to mention that AutoYaST `init` scripts are kind of limited and they do not support as -many features as other kind of scripts. - -| AutoYaST | Supported | Agama | Comment | -| -------- | --------- | ----- | ------- | -| location | Yes | url | | -| source | Yes | body | | -| filename | No | | -| rerun | No | | | - -### `services-manager` - -The `services-manager` section is used to define systemd services status. It is composed of a list -of services to enable and a list of services to disable. - -| AutoYaST | Supported | Agama | Comment | -| ----------------- | --------- | ----- | ------- | -| default_target | No | | | -| services.enable | Planned | | | -| services.disable | Planned | | | -| services.ondemand | Planned | | | - -At this point, it is possible to use post-scripts to enable/disable services. - -```jsonnet -{ - scripts: { - posts: [ - { - name: "post", - body: ||| - #!/bin/bash - systemctl enable sshd - |||, - }, - ] - } -} -``` - -### `software` - -The `software` section is composed of several lists: - -- A list of products to install, although a single value is expected. -- A list of patterns to install, a list of patterns to install in the 2nd stage and a list of - patterns to remove. -- A list of packages to install, a list of packages to install in the 2nd stage and a list of - packages to remove. - -Additionally, it is possible to force the installation of a specific kernel (`kernel`), perform an -online update at the end of the installation (`do_online_update`) or enable/disable the installation -of recommended packages (`install_recommended`). - -Only the product and the list of products or patterns are available for Agama. We might consider -adding support for the packages list and the `install_recommended` setting, although none are in the -web UI. - -| AutoYaST | Supported | Agama | Comment | -| ------------------- | --------- | ----------------- | ---------------------------------- | -| do_online_update | No | | No 2nd stage | -| install_recommended | No | | | -| instsource | No | | | -| kernel | No | | | -| packages | Planned | software.packages | | -| patterns | Partial | software.patterns | No support for regular expressions | -| post-packages | No | | No 2nd stage | -| post-patterns | No | | No 2nd stage | -| products | Yes | software.id | | -| remove-packages | No | | No upgrade | -| remove-patterns | No | | No upgrade | -| remove-products | No | | No upgrade | - -### `suse_register` - -Basic support for registering in the SUSE Customer Center is already in place, although there is no -way to select the list of add-ons. - -It is arguable whether we should offer a `install_updates` element instead of just installing them -(which is the use case for not installing them?). - -About the `slp_discovery` element, Agama does not support [SLP] at all? - -[SLP]: https://documentation.suse.com/sles/15-SP5/single-html/SLES-administration/#cha-slp - -| AutoYaST | Supported | Agama | Comment | -| -------------------------------- | --------- | ------------------------- | ------------------------------------ | -| do_registration | Yes | | The section is ignored if `false` | -| email | Yes | product.registrationEmail | | -| install_updates | Never | | | -| reg_code | Yes | product.registrationCode | | -| reg_server | Planned | | | -| reg_server_cert | Planned | | | -| reg_server_cert_fingerprint | Planned | | | -| reg_server_cert_fingerprint_type | Planned | | | -| addons | Undecided | | It is not clear how addons will work | -| slp_discovery | No | | | - -### `timezone` - -| AutoYaST | Supported | Agama | Comment | -| -------- | --------- | ------------- | ------- | -| timezone | Yes | l10n.timezone | | -| hwclock | No | | | - -## Unsupported sections - -- `FCoE` -- `add-on` -- `audit-laf` -- `auth-client` -- `configuration_management` -- `deploy_image` -- `dhcp-server` -- `dns-server` -- `files` -- `firstboot` -- `ftp-server` -- `groups` -- `host` -- `http-server` -- `mail` -- `nfs` -- `nfs_server` -- `nis` -- `nis_server` -- `ntp-client` -- `printer` -- `samba-client` -- `sound` -- `squid` -- `ssh_import` -- `sysconfig` -- `tftp-server` -- `upgrade` diff --git a/docs/user/autoyast/index.md b/docs/user/autoyast/index.md new file mode 100644 index 0000000..045a7b4 --- /dev/null +++ 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 new file mode 100644 index 0000000..e0a1110 --- /dev/null +++ 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 new file mode 100644 index 0000000..1ae1e4e --- /dev/null +++ b/docs/user/autoyast/reference.md @@ -0,0 +1,388 @@ +# AutoYaST compatibility reference + +Let's describe which sections and elements from an AutoYaST profile are (or will be) supported in +Agama. In some cases, you might find a table with the following columns: + +- AutoYaST: name of the AutoYaST element. +- Supported: whether it is (or will be) supported. The meaning of each value is: + - Yes: fully supported. + - Planned: not supported yet, but there are plans to support it. + - Undecided: no decision about whether it should be supported. + - No: there are no plans for supporting that element. +- Agama: name of the Agama element. +- Comment: any comment or reason about the element. + +## add-on + +This section is not supported. + +## audit-laf + +This section is not supported. + +## auth-client + +This section is not supported. + +## configuration_management + +This section is not supported. + +## deploy_image + +This section is not supported. + +## dhcp-server + +This section is not supported. + +## dns-server + +This section is not supported. + +## fcoe-client + +This section is not supported. + +## files + +There are plans to support this section in the future. + +## firstboot + +This section is not supported. + +## ftp-server + +This section is not supported. + +## general + +This section is not supported. + +## groups + +This section is not supported. + +## host + +This section is not supported. + +## http-server + +This section is not supported. + +## keyboard + +This section is supported. + +| AutoYaST | Supported | Agama | Notes | +| ---------- | --------- | ----------------------- | ----- | +| `keymap` | yes | `localization.keyboard` | | +| `capslock` | no | | | +| `delay` | no | | | +| `discaps` | no | | | +| `numlock` | no | | | +| `rate` | no | | | +| `scrlock` | no | | | +| `tty` | no | | | + +## language + +This section is supported. + +| AutoYaST | Supported | Agama | Notes | +| ----------- | --------- | ----------------------- | ----- | +| `language` | yes | `localization.language` | | +| `languages` | no | | | + +## networking + +This section is supported. + +| AutoYaST | Supported | Agama | Notes | +| ------------------------- | --------- | ----- | ----------------------------------- | +| `backend` | no | | Only NetworkManager is supported. | +| `dhcp_options` | no | | | +| `dns` | no | | | +| `ipv6` | yes | | It affects `method4` and `method6`. | +| `keep_install_network` | no | | | +| `managed` | no | | | +| `modules` | no | | | +| `net-udev` | no | | | +| `routing` | no | | | +| `s390-devices` | no | | | +| `setup_before_proposal` | no | | | +| `strict_IP_check_timeout` | no | | | +| `virt_bridge_proposal` | no | | | + +### networking/interfaces[] + +This section is supported. It corresponds to Agama `connections`, but the format is not exactly the +same. + +| AutoYaST | Supported | Agama | Notes | +| ------------------------------ | --------- | ------------------------------------ | ------------------------------------------------ | +| `device` | yes | `interface` | | +| `name` | yes | `id` | | +| `description` | no | | | +| `bootproto` | no | `method6` | Different set of values. | +| `startmode` | no | | Do not set up network connections you won't use. | +| `lladdr` | yes | `macAddress` | | +| `ifplugd_priority` | no | | Not relevant (no ifplugd support). | +| `usercontrol` | no | | | +| `dhclient_set_hostname` | no | | | +| `ipaddr` | yes | `network.connections[].address[]` | | +| `prefixlen` | yes | `network.connections[].address[]` | | +| `netmask` | yes | `network.connections[].address[]` | | +| `aliases` | yes | `network.connections[].address[]` | | +| `broadcast` | yes | `network.connections[].address[]` | | +| `network` | yes | `network.connections[].address[]` | | +| `mtu` | no | | | +| `ethtool_options` | no | | | +| `wireless` | yes | `wireless` | It uses a different format. | +| `dhclient_set_down_link` | no | | | +| `dhclient_set_default_route` | no | | | +| `zone` | no | | | +| `firewall` | no | | | +| `bonding_master` | planned | | | +| `bonding_module_opts` | yes | `network.connections[].bond.options` | | +| `bonding_slave0` | yes | `network.connections[].bond.ports` | | +| `bonding_slave1` | yes | `network.connections[].bond.ports` | | +| `bonding_slave2` | yes | `network.connections[].bond.ports` | | +| `bonding_slave3` | yes | `network.connections[].bond.ports` | | +| `bonding_slave4` | yes | `network.connections[].bond.ports` | | +| `bonding_slave5` | yes | `network.connections[].bond.ports` | | +| `bonding_slave6` | yes | `network.connections[].bond.ports` | | +| `bonding_slave7` | yes | `network.connections[].bond.ports` | | +| `bonding_slave8` | yes | `network.connections[].bond.ports` | | +| `bonding_slave9` | yes | `network.connections[].bond.ports` | | +| `bridge` | planned | | | +| `bridge_forwarddelay` | planned | | | +| `bridge_ports` | planned | | | +| `bridge_stp` | planned | | | +| `vlan_id` | planned | | | +| `wireless_auth_mode` | yes | | | +| `wireless_ap` | no | | | +| `wireless_bitrate` | no | | | +| `wireless_ca_cert` | no | | | +| `wireless_channel` | no | | | +| `wireless_client_cert` | no | | | +| `wireless_client_key` | no | | | +| `wireless_client_key_password` | no | | | +| `wireless_default_key` | no | | | +| `wireless_eap_auth` | no | | | +| `wireless_eap_mode` | no | | | +| `wireless_essid` | yes | `ssid` | | +| `wireless_frequency` | no | | | +| `wireless_key` | no | | | +| `wireless_key_0` | no | | | +| `wireless_key_1` | no | | | +| `wireless_key_2` | no | | | +| `wireless_key_3` | no | | | +| `wireless_key_length` | no | | | +| `wireless_mode` | yes | `mode` | | +| `wireless_nick` | no | | | +| `wireless_nwid` | no | | | +| `wireless_peap_version` | no | | | +| `wireless_power` | no | | | +| `wireless_wpa_anonid` | no | | | +| `wireless_wpa_identity` | no | | | +| `wireless_wpa_password` | yes | `password` | | +| `wireless_wpa_psk` | yes | `password` | | + +## services-manager + +There are plans to support this section in the future. Meanwhile you can use post-installation +scripts to handle these cases. + +## scripts + +This section is supported. + +### scripts/pre-scripts[] + +This section is supported. + +| AutoYaST | Supported | Agama | Notes | +| --------------- | --------- | -------------------- | ------------------------------------- | +| `filename` | yes | `scripts.pre[].name` | | +| `location` | yes | `scripts.pre[].url` | | +| `source` | yes | `scripts.pre[].body` | | +| `interpreter` | no | | Use the shebang line in your scripts. | +| `feedback` | no | | | +| `feedback_type` | no | | | +| `debug` | no | | | +| `notification` | no | | | +| `param-list` | no | | | +| `rerun` | no | | | + +### scripts/chroot-scripts[] + +This section is supported. + +| AutoYaST | Supported | Agama | Notes | +| --------------- | --------- | ----------------------- | ------------------------------------- | +| `filename` | yes | `scripts.chroot[].name` | | +| `location` | yes | `scripts.chroot[].url` | | +| `source` | yes | `scripts.chroot[].body` | | +| `interpreter` | no | | Use the shebang line in your scripts. | +| `feedback` | no | | | +| `feedback_type` | no | | | +| `debug` | no | | | +| `notification` | no | | | +| `param-list` | no | | | +| `rerun` | no | | | + +### scripts/post-scripts[] + +This section is supported. + +| AutoYaST | Supported | Agama | Notes | +| --------------- | --------- | --------------------- | ------------------------------------- | +| `filename` | yes | `scripts.init[].name` | | +| `location` | yes | `scripts.init[].url` | | +| `source` | yes | `scripts.init[].body` | | +| `interpreter` | no | | Use the shebang line in your scripts. | +| `feedback` | no | | | +| `feedback_type` | no | | | +| `debug` | no | | | +| `notification` | no | | | +| `param-list` | no | | | +| `rerun` | no | | | + +### scripts/init-scripts[] + +This section is supported. + +| AutoYaST | Supported | Agama | Notes | +| ---------- | --------- | --------------------- | ----- | +| `filename` | yes | `scripts.init[].name` | | +| `location` | yes | `scripts.init[].url` | | +| `source` | yes | `scripts.init[].body` | | +| `rerun` | no | | | + +## mail + +This section is not supported. + +## nfs + +This section is not supported. + +## nfs_server + +This section is not supported. + +## nis + +This section is not supported. + +## nis_server + +This section is not supported. + +## ntp-client + +This section is not supported. + +## printer + +This section is not supported. + +## proxy + +There are plans to support this section in the future. Meanwhile set the proxy +using the kernels' command line. + +## report + +This section is not supported. + +## samba-client + +This section is not supported. + +## software + +This section is supported. + +| AutoYaST | Supported | Agama | Notes | +| --------------------- | --------- | --------------------- | ------------ | +| `do_online_update` | no | | No 2nd stage | +| `install_recommended` | no | | | +| `instsource` | no | | | +| `kernel` | no | | | +| `packages[]` | planned | | | +| `post-packages[]` | no | | | +| `patterns[]` | yes | `software.patterns[]` | | +| `products[]` | yes | `software.id` | | +| `remove-packages[]` | no | | | +| `remove-patterns[]` | no | | | +| `remove-products[]` | no | | | + +## sound + +This section is not supported. + +## squid + +This section is not supported. + +## ssh_import + +This section is not supported. + +## suse_register + +This section is supported. + +| AutoYaST | Supported | Agama | Notes | +| ---------------------------------- | --------- | --------------------------- | ------------------------------------------------------ | +| `do_registration` | yes | | The whole suse_register section is ignored if "false". | +| `email` | yes | `product.registrationEmail` | | +| `install_updates` | no | | | +| `reg_code` | yes | `product.registrationCode` | | +| `reg_server` | planned | | | +| `reg_server_cert` | planned | | | +| `reg_server_cert_fingerprint` | planned | | | +| `reg_server_cert_fingerprint_type` | planned | | | +| `addons` | planned | | | +| `slp_discovery` | planned | | | + +## sysconfig + +This section is not supported. + +## tftp-server + +This section is not supported. + +## timezone + +This section is supported. + +| AutoYaST | Supported | Agama | Notes | +| ---------- | --------- | ----------------------- | ----- | +| `timezone` | yes | `localization.timezone` | | +| `hwclock` | no | | | + +## upgrade + +This section is not supported. + +## iscsi-client + +There are plans to support this section in the future. + +## users[] + +This section is supported. Only the root and the first user are considered. + +| AutoYaST | Supported | Agama | Notes | +| ----------------- | --------- | --------------------- | -------------------------------------------------------------- | +| `username` | yes | `user.userName` | | +| `fullName` | yes | `user.fullName` | | +| `password` | yes | `user.password` | | +| `encrypted` | yes | `user.hashedPassword` | If set to true, it uses "hashedPassword" instead of "password" | +| `authorized_keys` | yes | `root.sshPublicKey` | It only considers a single key. | diff --git a/docs/user/unattended/scripts.md b/docs/user/unattended/scripts.md index bad517b..6afc4e1 100644 --- 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 index b12fe59..773c356 100644 --- 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 new file mode 100644 index 0000000..de9603c --- /dev/null +++ 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.