[pmg-devel] [PATCH docs 0/8] improve & unify installation(-related) documentation

[pmg-devel] [PATCH docs 0/8] improve & unify installation(-related) documentation

[Christoph Heiss]

This series in short tries to bring the documentation for the
ISO installation flow and anything related to it in line the with
respective documentation for PVE. As both products use the same
installer (minus small differences such as LVM options and BTRFS
support) and overall same basic system setup, it is worth to unify them.

This also brings the benefit that future changes should be more easily
adaptable to both.

As this essentially takes the "best of both worlds" in tries to combine
them, an accompanying series is also provided for `pve-docs` on the
respective mailing list - so please also take a look there.

FWIW; happy to further improve these sections if there suggestions,
since I'm already changing a lot anyway.

Christoph Heiss (8):
  gitignore: add package build outputs
  getting-help: align wording with respective pve-docs page
  getting-help: add mailing lists link
  installation: repos: improve & align wording with pve-docs
  installation: iso: improve & align wording with pve-docs
  installation: lvm-options: improve & align wording with pve-docs
  installation: debian: improve & align wording with pve-docs
  installation: zfs: add advanced zfs configuration section

 .gitignore            |   4 +
 getting-help.adoc     |  40 +++++---
 pmg-installation.adoc | 232 ++++++++++++++++++++++++------------------
 3 files changed, 165 insertions(+), 111 deletions(-)

--
2.43.0

[pmg-devel] [PATCH docs 1/8] gitignore: add package build outputs

[Christoph Heiss]

.. much like it many other repos.

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 .gitignore | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/.gitignore b/.gitignore
index cc6f722..0a3dde3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,9 @@
 *.tmp
 *.epub
 *.swp
+/*.deb
+/*.changes
+/*.buildinfo
 /#*#
 /.pmg-doc-depends
 /api-viewer/apidoc.js
@@ -16,3 +19,4 @@
 /man8-index-table.adoc
 /pmg-doc-generator.mk
 /pmg-copyright.adoc
+/pmg-docs-[0-9]*/
-- 
2.43.0

[pmg-devel] [PATCH docs 2/8] getting-help: align wording with respective pve-docs page

[Christoph Heiss]

Makes it much more consistent and a bit easier to integrate future
changes to both pages as needed.

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 getting-help.adoc     | 31 +++++++++++++++++--------------
 pmg-installation.adoc |  1 +
 2 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/getting-help.adoc b/getting-help.adoc
index 47bb92e..5653412 100644
--- a/getting-help.adoc
+++ b/getting-help.adoc
@@ -11,27 +11,30 @@ Community Support Forum
 
 {pmg} itself is fully open source, so we always encourage our users to
 discuss and share their knowledge using the {forum}. The forum is
-moderated by the Proxmox support team, and has a large user base
-around the world. Needless to say, such a large forum is a
-great place to get information.
+moderated by the Proxmox support team, and has a large user base from all
+around the world. Needless to say, such a large forum is a great place to
+get information.
 
 
 Commercial Support
 ~~~~~~~~~~~~~~~~~~
 
-{proxmoxGmbh} also offers commercial {pricing-url}[{pmg} Subscription
-Service Plans]. Users with a Basic subscription or above
-have access to a dedicated support portal with guaranteed response
-times, where {pmg} developers can help them, should an issue appear. Please
-contact the mailto:sales@proxmox.com[Proxmox sales team] for more
-information or volume discounts.
+{proxmoxGmbh} also offers enterprise support available as
+{pricing-url}[{pmg} Subscription Service Plans].
+All users with a subscription get access to the {pmg}
+xref:pmg_enterprise_repository[Enterprise Repository], and--with a Basic,
+Standard or Premium subscription--also to the Proxmox Customer Portal. The
+customer portal provides help and support with guaranteed response times from
+the {pmg} developers.
+
+For volume discounts, or more information in general, please contact
+mailto:sales@proxmox.com[sales@proxmox.com].
 
 
 Bug Tracker
 ~~~~~~~~~~~
 
-We also run a public bug tracker at
-https://bugzilla.proxmox.com. If you ever detect a bug, you can file
-a bug entry there. This makes it easy to track the bug's status and
-get notified as soon as the bug is fixed.
-
+Proxmox runs a public bug tracker at https://bugzilla.proxmox.com. If an issue
+appears, file your report there. An issue can be a bug as well as a request for
+a new feature or enhancement. The bug tracker helps to keep track of the issue
+and will send a notification once it has been solved.
diff --git a/pmg-installation.adoc b/pmg-installation.adoc
index 25d16a7..ac6a9af 100644
--- a/pmg-installation.adoc
+++ b/pmg-installation.adoc
@@ -413,6 +413,7 @@ deb http://security.debian.org/debian-security bookworm-security main contrib
 {pmg} provides three different package repositories.
 
 
+[[pmg_enterprise_repository]]
 {pmg} Enterprise Repository
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.43.0

[pmg-devel] [PATCH docs 3/8] getting-help: add mailing lists link

[Christoph Heiss]

We have the same section already in pve-docs, it's a nice addition for
pmg-docs too.

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 getting-help.adoc | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/getting-help.adoc b/getting-help.adoc
index 5653412..5f296a2 100644
--- a/getting-help.adoc
+++ b/getting-help.adoc
@@ -15,6 +15,15 @@ moderated by the Proxmox support team, and has a large user base from all
 around the world. Needless to say, such a large forum is a great place to
 get information.
 
+Mailing Lists
+~~~~~~~~~~~~~
+
+{pmg} is fully open source and contributions are welcome! The primary
+communication channel for developers is the:
+
+* Mailing list for developers:
+  http://lists.proxmox.com/cgi-bin/mailman/listinfo/pmg-devel[{PMG} development
+  discussion]
 
 Commercial Support
 ~~~~~~~~~~~~~~~~~~
-- 
2.43.0

[pmg-devel] [PATCH docs 4/8] installation: repos: improve & align wording with pve-docs

[Christoph Heiss]

Most of the changes are taken from pve-docs to align the exact wording
in general, as well as changing a few subtle things to improve the
overall reading flow.

The equivalent changes will be done for pve-docs too to ensure they are
really the same in the end.

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 pmg-installation.adoc | 53 +++++++++++++++++++++----------------------
 1 file changed, 26 insertions(+), 27 deletions(-)

diff --git a/pmg-installation.adoc b/pmg-installation.adoc
index ac6a9af..8cac842 100644
--- a/pmg-installation.adoc
+++ b/pmg-installation.adoc
@@ -348,10 +348,10 @@ used, ensure that the container always leases the same IP, for example, by
 reserving one with the container's network MAC address.
 
 Additionally, you can install this on top of a container-based Debian
-installation. After configuring the
-xref:pmg_package_repositories[package repositories], you need to run:
+installation.
+xref:pmg_package_repositories[After configuring the repositories], you need to
+run:
 
-[source,bash]
 ----
 apt update
 apt install proxmox-mailgateway-container
@@ -427,19 +427,19 @@ enabled by default:
 deb https://enterprise.proxmox.com/debian/pmg bookworm pmg-enterprise
 ----
 
-As soon as updates are available, the `root@pam` user is notified via
-email about the newly available packages. From the GUI, the change-log of
-each package can be viewed (if available), showing all details of the
-update. Thus, you will never miss important security fixes.
+As soon as updates are available, the `root@pam` user is notified via email
+about the newly available packages. From the GUI, the 'Changelog' button in the
+GUI can be used to see more details about the selected update.
+Thus, you will never miss important security fixes.
 
-Please note that you need a valid subscription key to access this
-repository. We offer different support levels, which you can find further
-details about at {pricing-url}.
+Please note that you need a valid subscription key to access the
+`pmg-enterprise` repository. We offer different support levels, which you can
+find further details about at {pricing-url}.
 
-NOTE: You can disable this repository by commenting out the above line
-using a `#` (at the start of the line). This prevents error messages,
-if you do not have a subscription key. Please configure the
-`pmg-no-subscription` repository in this case.
+NOTE: You can disable this repository by commenting out the above line using a
+`#` (at the start of the line). This prevents error messages if your host does
+not have a subscription key. Please configure the `pmg-no-subscription`
+repository in that case.
 
 
 {pmg} No-Subscription Repository
@@ -469,30 +469,29 @@ deb http://download.proxmox.com/debian/pmg bookworm pmg-no-subscription
 {pmg} Test Repository
 ~~~~~~~~~~~~~~~~~~~~~
 
-Finally, there is a repository called `pmgtest`. This contains the
-latest packages, and is heavily used by developers to test new
-features. As with before, you can configure this using
-`/etc/apt/sources.list` by adding the following line:
+This repository contains the latest packages and is primarily used by developers
+to test new features. To configure it, add the following line to
+`/etc/apt/sources.list`:
 
 .sources.list entry for `pmgtest`
 ----
 deb http://download.proxmox.com/debian/pmg bookworm pmgtest
 ----
 
-WARNING: the `pmgtest` repository should only be used
-for testing new features or bug fixes.
-
+WARNING: The `pmgtest` repository should (as the name implies) only be used for
+testing new features or bug fixes.
 
 SecureApt
 ~~~~~~~~~
 
-We use GnuPG to sign the `Release` files inside these repositories,
-and APT uses these signatures to verify that all packages are from a
-trusted source.
+The 'Release' files in the repositories are signed with GnuPG. APT is using
+these signatures to verify that all packages are from a trusted source.
+
+If you install {pmg} from an official ISO image, the key for verification is
+already installed.
 
-The key used for verification is already installed, if you install from
-our installation CD. If you install via another means, you can manually
-download the key by executing the following command as root user:
+If you install {pmg} on top of Debian, download and install
+the key by executing the following commands as `root` user:
 
 ----
  # wget https://enterprise.proxmox.com/debian/proxmox-release-bookworm.gpg -O /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg
-- 
2.43.0

[pmg-devel] [PATCH docs 5/8] installation: iso: improve & align wording with pve-docs

[Christoph Heiss]

Most of the changes are taken from pve-docs to align the exact wording
in general, as well as changing a few subtle things to improve the
overall reading flow.

The equivalent changes will be done for pve-docs too to ensure they are
really the same in the end.

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 pmg-installation.adoc | 110 ++++++++++++++++++++++--------------------
 1 file changed, 57 insertions(+), 53 deletions(-)

diff --git a/pmg-installation.adoc b/pmg-installation.adoc
index 8cac842..bd6fd33 100644
--- a/pmg-installation.adoc
+++ b/pmg-installation.adoc
@@ -1,5 +1,5 @@
-Installation
-============
+Installing {pmg}
+================
 
 {pmg} is based on Debian. This is why the install disk images (ISO files)
 provided by Proxmox include a complete Debian system as well as all necessary
@@ -8,11 +8,11 @@ provided by Proxmox include a complete Debian system as well as all necessary
 TIP: See the xref:faq-support-table[support table in the FAQ] for the
 relationship between {pmg} releases and Debian releases.
 
-The installer will guide you through the setup, allowing you to partition the local
-disk(s), apply basic system configurations (for example, timezone, language,
-network) and install all required packages. This process should not take more
-than a few minutes. Installing with the provided ISO is the recommended method
-for new and existing users.
+The installer will guide you through the setup, allowing you to partition the
+local disk(s), apply basic system configurations (for example, time zone,
+language, network) and install all required packages. This process should not
+take more than a few minutes. Installing with the provided ISO is the
+recommended method for new and existing users.
 
 Alternatively, {pmg} can be installed on top of an existing Debian system. This
 option is only recommended for advanced users because detailed knowledge about
@@ -21,8 +21,8 @@ option is only recommended for advanced users because detailed knowledge about
 include::pmg-installation-media.adoc[]
 
 [[pmg_install_iso]]
-Using the {pmg} Installation CD-ROM
------------------------------------
+Using the {pmg} Installer
+-------------------------
 
 The installer ISO image includes the following:
 
@@ -31,15 +31,15 @@ The installer ISO image includes the following:
 * The {pmg} installer, which partitions the hard drive(s) with ext4,
   XFS or ZFS and installs the operating system
 
-* Linux kernel
+* {pmg} Linux kernel
 
 * Postfix MTA, ClamAV, Spamassassin and the {pmg} toolset
 
 * Web-based management interface for using the toolset
 
-NOTE: All existing data on the for installation selected drives will be removed
-during the installation process. The installer does not add boot menu entries
-for other operating systems.
+NOTE: All existing data on the selected drives will be removed during the
+installation process. The installer does not add boot menu entries for other
+operating systems.
 
 Please insert the xref:installation_prepare_media[prepared installation media]
 (for example, USB flash drive or CD-ROM) and boot from it.
@@ -50,12 +50,12 @@ when booting an installer prior to {pmg} version 8.1.
 
 [thumbnail="installer/pmg-grub-menu.png"]
 
-After choosing the correct entry (for example, Boot from USB) the {pmg} menu
+After choosing the correct entry (for example, 'Boot from USB') the {pmg} menu
 will be displayed, and one of the following options can be selected:
 
 Install {pmg} (Graphical)::
 
-Start normal installation.
+Starts the normal installation.
 
 TIP: It's possible to use the installation wizard with a keyboard only. Buttons
 can be clicked by pressing the `ALT` key combined with the underlined character
@@ -67,13 +67,6 @@ Starts the terminal-mode installation wizard. It provides the same overall
 installation experience as the graphical installer, but has generally better
 compatibility with very old and very new hardware.
 
-Install {pmg} (Terminal UI, Serial Console)::
-
-Starts the terminal-mode installation wizard, additionally setting up the Linux
-kernel to use the (first) serial port of the machine for in- and output. This
-can be used if the machine is completely headless and only has a serial console
-available.
-
 [thumbnail="installer/pmg-tui-installer.png"]
 
 Both modes use the same code base for the actual installation process to
@@ -82,6 +75,13 @@ benefit from more than a decade of bug fixes and ensure feature parity.
 TIP: The 'Terminal UI' option can be used in case the graphical installer does
 not work correctly, due to e.g. driver issues.
 
+Install {pmg} (Terminal UI, Serial Console)::
+
+Starts the terminal-mode installation wizard, additionally setting up the Linux
+kernel to use the (first) serial port of the machine for in- and output. This
+can be used if the machine is completely headless and only has a serial console
+available.
+
 Advanced Options: Install {pmg} (Graphical, Debug Mode)::
 
 Starts the installation in debug mode. A console will be opened at several
@@ -128,63 +128,66 @@ installation.
 The `Options` button lets you select the target file system, which
 defaults to `ext4`. The installer uses LVM if you select
 `ext4` or `xfs` as a file system, and offers additional options to
-restrict LVM space (see <<advanced_lvm_options,below>>)
+restrict LVM space (see xref:advanced_lvm_options[below]).
 
-If you have more than one disk, you can also use ZFS as a file system.
-ZFS supports several software RAID levels, which is particularly useful
-if you do not have a hardware RAID controller. The `Options` button
-lets you choose the ZFS RAID level and select which disks will be used.
+{pmg} can also be installed on ZFS. As ZFS offers several software RAID levels,
+this is an option for systems that don't have a hardware RAID controller. The
+target disks must be selected in the `Options` dialog. More ZFS specific
+settings can be changed under `Advanced Options`.
 
 WARNING: ZFS on top of any hardware RAID is not supported and can result in data
 loss.
 
 [thumbnail="installer/pmg-select-location.png"]
 
-The next page asks for basic configuration options like your
-location, timezone, and keyboard layout. The location is used to
-select a nearby download server, in order to increase the speed of updates.
-The installer is usually able to auto-detect these settings, so you only need to
-change them in rare situations when auto-detection fails, or when you want to
-use a keyboard layout not commonly used in your country.
+The next page asks for basic configuration options like your location, time
+zone, and keyboard layout. The location is used to select a nearby download
+server, in order to increase the speed of updates. The installer is usually able
+to auto-detect these settings, so you only need to change them in rare
+situations when auto-detection fails, or when you want to use a keyboard layout
+not commonly used in your country.
 
 [thumbnail="installer/pmg-set-password.png", float="left"]
 
-You then need to specify an email address and the superuser (root)
-password. The password must have at least 5 characters, but we highly
-recommend to use stronger passwords - here are some guidelines:
+Next the password of the superuser (`root`) and an email address needs to be
+specified. The password must consist of at least 5 characters. It's highly
+recommended to use a stronger password. Some guidelines are:
 
 - Use a minimum password length of at least 12 characters.
 
 - Include lowercase and uppercase alphabetic characters, numbers and symbols.
 
-- Avoid character repetition, keyboard patterns, dictionary words, letter or
-  number sequences, usernames, relative or pet names, romantic links (current
-  or past) and biographical information (e.g., ID numbers, ancestors' names or
-  dates).
+- Avoid character repetition, keyboard patterns, common dictionary words,
+  letter or number sequences, usernames, relative or pet names, romantic links
+  (current or past), and biographical information (for example ID numbers,
+  ancestors' names or dates).
 
-It is sometimes necessary to send notification to the system administrator, for
-example:
+The email address is used to send notifications to the system administrator.
+For example:
 
 - Information about available package updates.
 
-- Error messages from periodic cron jobs.
+- Error messages from periodic 'cron' jobs.
 
 [thumbnail="installer/pmg-setup-network.png"]
 
 All those notification mails will be sent to the specified email address.
 
-The next step is the network configuration. Please note that you can use either
-IPv4 or IPv6 here, but not both. If you want to configure a dual stack node,
-you can easily do that after the installation.
+The last step is the network configuration. Network interfaces that are 'UP'
+show a filled circle in front of their name in the drop down menu. Please note
+that during installation you can either specify an IPv4 or IPv6 address, but not
+both. To configure a dual stack node, add additional IP addresses after the
+installation.
 
 [thumbnail="installer/pmg-installation.png", float="left"]
 
-When you press `Next`, you will see an overview of your entered configuration.
-Please re-check every setting, you can still use the `Previous` button to go
-back and edit any settings.
+The next step shows a summary of the previously selected options. Please
+re-check every setting and use the `Previous` button if a setting needs to be
+changed.
 
-After clicking `Install`, the installer will begin to format and copy packages
-to the target disk(s).
+After clicking `Install`, the installer will begin to format the disks and copy
+packages to the target disk(s). Please wait until this step has finished; then
+remove the installation medium and restart your system.
 
 [thumbnail="installer/pmg-summary.png"]
 
@@ -197,7 +200,7 @@ server. This will be done automatically after a few seconds by default.
 .Installation Failure
 
 If the installation failed, check out specific errors on the second TTY
-(`CTRL + ALT + F2') and ensure that the systems meets the
+('CTRL + ALT + F2') and ensure that the systems meets the
 xref:install_minimal_requirements[minimum requirements].
 
 If the installation is still not working, look at the xref:getting_help[how to
@@ -215,7 +218,8 @@ web interface for further configuration.
 . Point your browser to the IP address given during the installation and port
   8006, for example: https://youripaddress:8006
 
-. Log in using the `root` username and the password chosen during installation.
+. Log in using the `root` (realm 'PAM') username and the password chosen during
+installation.
 
 . Upload your subscription key to gain access to the Enterprise repository.
   Otherwise, you will need to set up one of the public, less tested package
-- 
2.43.0

[pmg-devel] [PATCH docs 6/8] installation: lvm-options: improve & align wording with pve-docs

[Christoph Heiss]

Most of the changes are taken from pve-docs to align the exact wording
in general, as well as changing a few subtle things to improve the
overall reading flow.

The equivalent changes will be done for pve-docs too to ensure they are
really the same in the end.

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 pmg-installation.adoc | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/pmg-installation.adoc b/pmg-installation.adoc
index bd6fd33..26f2dc8 100644
--- a/pmg-installation.adoc
+++ b/pmg-installation.adoc
@@ -251,21 +251,23 @@ traffic you need to change the existing email server configuration.
 Advanced LVM Configuration Options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The installer creates a Volume Group (VG) called `pmg`, and additional
-Logical Volumes (LVs) called `root` and `swap`. The size of
-those volumes can be controlled with:
+The installer creates a Volume Group (VG) called `pmg`, and additional Logical
+Volumes (LVs) called `root`, `data`, and `swap`, if `ext4` or `xfs` is used. To
+control the size of these volumes use:
 
 `hdsize`::
 
-Defines the total disk size to be used. This way you can save free
-space on the disk for further partitioning (i.e. for an additional PV
-and VG on the same disk that can be used for LVM storage).
+Defines the total hard disk size to be used. This way you can reserve free space
+on the hard disk for further partitioning (for example for an additional PV and
+VG on the same hard disk that can be used for LVM storage).
 
 `swapsize`::
 
 Defines the size of the `swap` volume. The default is the size of the
 installed memory. The minimum is 4 GB and the maximum is 8 GB. The resulting
 value cannot be greater than `hdsize/8`.
++
+NOTE: If set to `0`, no `swap` volume will be created.
 
 `minfree`::
 
-- 
2.43.0

[pmg-devel] [PATCH docs 7/8] installation: debian: improve & align wording with pve-docs

[Christoph Heiss]

Most of the changes are taken from pve-docs to align the exact wording
in general, as well as changing a few subtle things to improve the
overall reading flow.

The equivalent changes will be done for pve-docs too to ensure they are
really the same in the end.

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 pmg-installation.adoc | 20 +++++++++-----------
 1 file changed, 9 insertions(+), 11 deletions(-)

diff --git a/pmg-installation.adoc b/pmg-installation.adoc
index 26f2dc8..ae60ea9 100644
--- a/pmg-installation.adoc
+++ b/pmg-installation.adoc
@@ -315,24 +315,22 @@ Then press `Ctrl-X` or `F10` to boot the configuration.
 Install {pmg} on Debian
 -----------------------
 
-{pmg} ships as a set of Debian packages, so you can install it
-on top of a normal Debian installation. After configuring the
-xref:pmg_package_repositories[package repositories], you need to run:
+{pmg} ships as a set of Debian packages and can be installed on top of a
+standard Debian installation.
+xref:pmg_package_repositories[After configuring the repositories], you need
+to run the following commands:
 
-[source,bash]
 ----
 apt update
 apt install proxmox-mailgateway
 ----
 
-Installing on top of an existing Debian installation seems easy, but
-it assumes that you have correctly installed the base system, and you
-know how you want to configure and use the local storage. Network
-configuration is also completely up to you.
-
-NOTE: In general, this is not trivial, especially when you use LVM or
-ZFS.
+Installing on top of an existing Debian installation looks easy, but it presumes
+that the base system has been installed correctly and that you know how you want
+to configure and use the local storage. You also need to configure the network
+manually.
 
+NOTE: In general, this is not trivial, especially when LVM or ZFS is used.
 
 [[pmg_install_on_debian_container]]
 Install {pmg} as a Linux Container Appliance
-- 
2.43.0

[pmg-devel] [PATCH docs 8/8] installation: zfs: add advanced zfs configuration section

[Christoph Heiss]

Copied from pve-docs, applies here the same as well.

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 pmg-installation.adoc | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/pmg-installation.adoc b/pmg-installation.adoc
index ae60ea9..51c6b80 100644
--- a/pmg-installation.adoc
+++ b/pmg-installation.adoc
@@ -133,7 +133,7 @@ restrict LVM space (see xref:advanced_lvm_options[below]).
 {pmg} can also be installed on ZFS. As ZFS offers several software RAID levels,
 this is an option for systems that don't have a hardware RAID controller. The
 target disks must be selected in the `Options` dialog. More ZFS specific
-settings can be changed under `Advanced Options`.
+settings can be changed under xref:advanced_zfs_options[`Advanced Options`].
 
 WARNING: ZFS on top of any hardware RAID is not supported and can result in data
 loss.
@@ -278,6 +278,40 @@ Defines the amount of free space that should be left in the LVM volume group
 NOTE: LVM requires free space in the VG for snapshot creation (not
 required for lvmthin snapshots).
 
+[[advanced_zfs_options]]
+Advanced ZFS Configuration Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The installer creates the ZFS pool `rpool`, if ZFS is used. No swap space is
+created but you can reserve some unpartitioned space on the install disks for
+swap. You can also create a swap zvol after the installation, although this can
+lead to problems.
+
+`ashift`::
+
+Defines the `ashift` value for the created pool. The `ashift` needs to be set at
+least to the sector-size of the underlying disks (2 to the power of `ashift` is
+the sector-size), or any disk which might be put in the pool (for example the
+replacement of a defective disk).
+
+`compress`::
+
+Defines whether compression is enabled for `rpool`.
+
+`checksum`::
+
+Defines which checksumming algorithm should be used for `rpool`.
+
+`copies`::
+
+Defines the `copies` parameter for `rpool`. Check the `zfs(8)` manpage for the
+semantics, and why this does not replace redundancy on disk-level.
+
+`hdsize`::
+
+Defines the total hard disk size to be used. This is useful to save free space
+on the hard disk(s) for further partitioning (for example to create a
+swap-partition). `hdsize` is only honored for bootable disks, that is only the
+first disk or mirror for RAID0, RAID1 or RAID10, and all disks in RAID-Z[123].
 
 ZFS Performance Tips
 ~~~~~~~~~~~~~~~~~~~~
-- 
2.43.0