[pve-devel] [RFC PATCH docs-common 05/13] partials: add advanced installation hints from pve-docs

[Christoph Heiss]

Signed-off-by: Christoph Heiss <c.heiss at proxmox.com>
---
 partials/advanced-installation.adoc | 125 ++++++++++++++++++++++++++++
 1 file changed, 125 insertions(+)
 create mode 100644 partials/advanced-installation.adoc

diff --git a/partials/advanced-installation.adoc b/partials/advanced-installation.adoc
new file mode 100644
index 0000000..ed2709f
--- /dev/null
+++ b/partials/advanced-installation.adoc
@@ -0,0 +1,125 @@
+[[advanced_lvm_options]]
+Advanced LVM Configuration Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The installer creates a Volume Group (VG) called `pve`, 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 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, minimum 4 GB and maximum 8 GB. The resulting value cannot be greater
+than `hdsize/8`.
++
+NOTE: If set to `0`, no `swap` volume will be created.
+
+`maxroot`::
+
+Defines the maximum size of the `root` volume, which stores the operation
+system. The maximum limit of the `root` volume size is `hdsize/4`.
+
+`maxvz`::
+
+Defines the maximum size of the `data` volume. The actual size of the `data`
+volume is:
++
+`datasize = hdsize - rootsize - swapsize - minfree`
++
+Where `datasize` cannot be bigger than `maxvz`.
++
+NOTE: In case of LVM thin, the `data` pool will only be created if `datasize` is
+bigger than 4GB.
++
+NOTE: If set to `0`, no `data` volume will be created and the storage
+configuration will be adapted accordingly.
+
+`minfree`::
+
+Defines the amount of free space that should be left in the LVM volume group
+`pve`. With more than 128GB storage available, the default is 16GB, otherwise
+`hdsize/8` will be used.
++
+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 (see xref:zfs_swap[ZFS swap notes]).
+
+`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.
+
+`ARC max size`::
+
+Defines the maximum size the ARC can grow to and thus limits the amount of
+memory ZFS will use. See also the section on
+xref:sysadmin_zfs_limit_memory_usage[how to limit ZFS memory usage] for more
+details.
+
+`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
+~~~~~~~~~~~~~~~~~~~~
+
+ZFS works best with a lot of memory. If you intend to use ZFS make sure to have
+enough RAM available for it. A good calculation is 4GB plus 1GB RAM for each TB
+RAW disk space.
+
+ZFS can use a dedicated drive as write cache, called the ZFS Intent Log (ZIL).
+Use a fast drive (SSD) for it. It can be added after installation with the
+following command:
+
+----
+# zpool add <pool-name> log </dev/path_to_fast_ssd>
+----
+
+[[nomodeset_kernel_param]]
+Adding the `nomodeset` Kernel Parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Problems may arise on very old or very new hardware due to graphics drivers. If
+the installation hangs during boot, you can try adding the `nomodeset`
+parameter. This prevents the Linux kernel from loading any graphics drivers and
+forces it to continue using the BIOS/UEFI-provided framebuffer.
+
+On the {pve} bootloader menu, navigate to 'Install {pve} (Terminal UI)' and
+press `e` to edit the entry. Using the arrow keys, navigate to the line starting
+with `linux`, move the cursor to the end of that line and add the
+parameter `nomodeset`, separated by a space from the pre-existing last
+parameter.
+
+Then press `Ctrl-X` or `F10` to boot the configuration.
--
2.44.0