[pve-devel] [RFC PATCH docs{, -common} 0/13] introduce common documentation base

[pve-devel] [RFC PATCH docs{, -common} 0/13] introduce common documentation base

[Christoph Heiss]

tl;dr: Introduce a separate repository for shared documentation between
all three products.

This proposes the introduction of a - aptly named - proxmox-docs-common
repo, which can be used for all documentation not specific to a single
product.

Marked RFC to gather feedback from other people. After talking to some
people off-list, there definitely is the need for something like this in
the long run.

For now, this is pve-docs only, with only one page and two partials (see
also "Organization"). But it shows the purpose and general approach well
enough to gather some first feedback.

Motivation
==========
A lot of pages and sections esp. from pve-docs apply to all three
products. To name a few; package repos, (firmware) updates, network
config, ZFS host administration, bootloader etc. etc.

Further, the documentation for the auto-installer from Aaron (now in the
wiki) and for the notification system from Lukas would also be good fit
for proxmox-docs-common.

The plan would be to gradually move them all into proxmox-docs-common as
appropriate, thus de-duplicating and having them available on all three
products without the headaches of copying & keeping them in sync.

Most of the common documentation is now done via the wiki, but this
approach would allow "codifying" these things - generating wiki pages
from our documentation is a solved problem already.

Organization
============
Pretty simple; all files in the repo root of proxmox-docs-common
represent "full pages", i.e. starting with a level-1 heading, much like
in pve-docs. These must still each be included somewhere, e.g. for
pve-docs the appropriate subpage or in `pve-admin-guide.adoc`.

Additionally, there is the `partials/` folder, which contains exactly
that - these are sections of pages (aka. with no level-1 heading) that
can be shared, but where the whole page might might not be suitable for
sharing. These can be then included as usual using

  include::proxmox-docs-common/partials/foo.adoc[]

The distinction is only for organization in the repo itself, but
otherwise has no special/hidden meaning. So this can easily be
changed/dropped if desired.

Future works
============
- Integrating into pmg-docs
- Integrating ReStructuredText
- Integrating into proxmox-backup documentation
- Moving more pages and sections into it, of course - lots to be done
  there
- Unifying the `scan-adoc-refs` tool from {pve,pmg}-docs in the common
  repo

AsciiDoc vs. ReStructuredText
=============================
Currently, this is AsciiDoc only.

My proposal would be to keep all exisiting AsciiDoc pages as such and
only adapt as necessary. Since it is possible to automatically convert
between AsciiDoc and ReStructuredText, this means we can reuse
existing AsciiDoc-written pages/partials in PBS and write new pages in
ReStructuredText.

The latter is not included in this series yet, but would be a follow-up
in the future, to keep this initial change as simple as possible.

[ Of course, one could also think about mechanically converting all
  AsciiDoc-written pages to ReStructuredText, but that's a whole
  different story and harder to get right. ]

Diffstats
=========
Looks a bit scary, but the bulk of it are simply renames & pulling
sections out into different files. For the latter, there is always a
commit for copying the content 1:1 and one adapting small things as
necessary.

pve-docs:

Christoph Heiss (7):
  gitmodules: add proxmox-docs-common
  scan-adoc-refs: enable building pages from proxmox-docs-common/ subdir
  images: strip `pve-` prefix from screenshots used in common docs
  asciidoc: conf: add iso-url variable
  installation-media: move to common docs
  installation: use new 'installation-flow' partial from common docs
  installation: use new 'advanced-installation' partial from common docs

 .gitmodules                                   |   3 +
 Makefile                                      |   6 +-
 asciidoc/asciidoc-pve.conf                    |   3 +
 .../{pve-grub-menu.png => grub-menu.png}      | Bin
 .../{pve-grub-menu.ppm => grub-menu.ppm}      | Bin
 ...nstall-summary.png => install-summary.png} | Bin
 ...nstall-summary.ppm => install-summary.ppm} | Bin
 ...{pve-installation.png => installation.png} | Bin
 ...{pve-installation.ppm => installation.ppm} | Bin
 ...elect-location.png => select-location.png} | Bin
 ...elect-location.ppm => select-location.ppm} | Bin
 ...target-disk.png => select-target-disk.png} | Bin
 ...target-disk.ppm => select-target-disk.ppm} | Bin
 ...{pve-set-password.png => set-password.png} | Bin
 ...{pve-set-password.ppm => set-password.ppm} | Bin
 ...ve-setup-network.png => setup-network.png} | Bin
 ...ve-setup-network.ppm => setup-network.ppm} | Bin
 ...ve-tui-installer.png => tui-installer.png} | Bin
 ...ve-tui-installer.ppm => tui-installer.ppm} | Bin
 png-verify.pl                                 |  14 +-
 proxmox-docs-common                           |   1 +
 pve-doc-generator.mk.in                       |   6 +
 pve-installation-media.adoc                   | 132 --------
 pve-installation.adoc                         | 300 +-----------------
 scan-adoc-refs                                |  25 +-
 25 files changed, 44 insertions(+), 446 deletions(-)
 create mode 100644 .gitmodules
 rename images/screenshot/{pve-grub-menu.png => grub-menu.png} (100%)
 rename images/screenshot/{pve-grub-menu.ppm => grub-menu.ppm} (100%)
 rename images/screenshot/{pve-install-summary.png => install-summary.png} (100%)
 rename images/screenshot/{pve-install-summary.ppm => install-summary.ppm} (100%)
 rename images/screenshot/{pve-installation.png => installation.png} (100%)
 rename images/screenshot/{pve-installation.ppm => installation.ppm} (100%)
 rename images/screenshot/{pve-select-location.png => select-location.png} (100%)
 rename images/screenshot/{pve-select-location.ppm => select-location.ppm} (100%)
 rename images/screenshot/{pve-select-target-disk.png => select-target-disk.png} (100%)
 rename images/screenshot/{pve-select-target-disk.ppm => select-target-disk.ppm} (100%)
 rename images/screenshot/{pve-set-password.png => set-password.png} (100%)
 rename images/screenshot/{pve-set-password.ppm => set-password.ppm} (100%)
 rename images/screenshot/{pve-setup-network.png => setup-network.png} (100%)
 rename images/screenshot/{pve-setup-network.ppm => setup-network.ppm} (100%)
 rename images/screenshot/{pve-tui-installer.png => tui-installer.png} (100%)
 rename images/screenshot/{pve-tui-installer.ppm => tui-installer.ppm} (100%)
 create mode 160000 proxmox-docs-common
 delete mode 100644 pve-installation-media.adoc

proxmox-docs-common:

Christoph Heiss (6):
  installation-media: move page from pve-docs here
  installation-media: adapt for common usage
  partials: add installation flow from pve-docs
  partials: installation-flow: adapt from pve-docs
  partials: add advanced installation hints from pve-docs
  partials: advanced-installation: adapt from pve-docs

 installation-media.adoc             |  21 +++++++++++++++++++++++++++--
 partials/advanced-installation.adoc | 125 ++++++++++++++++++++
 partials/installation-flow.adoc     | 171 ++++++++++++++++++++++++++++
 3 files changed, 440 insertions(+), 9 deletions(-)
 create mode 100644 installation-media.adoc
 create mode 100644 partials/advanced-installation.adoc
 create mode 100644 partials/installation-flow.adoc

--
2.42.0



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [RFC PATCH docs-common 01/13] installation-media: move page from pve-docs here

[Christoph Heiss]

Small adaptions were necessary; mostly a s/{pve}/{product}/g and
replacing the ISO URL with the {iso-url} variable.

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 installation-media.adoc | 132 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 132 insertions(+)
 create mode 100644 installation-media.adoc

diff --git a/installation-media.adoc b/installation-media.adoc
new file mode 100644
index 0000000..a1c9402
--- /dev/null
+++ b/installation-media.adoc
@@ -0,0 +1,132 @@
+[[installation_prepare_media]]
+Prepare Installation Media
+--------------------------
+ifdef::wiki[]
+:pve-toplevel:
+endif::wiki[]
+
+Download the installer ISO image from: {website}en/downloads/proxmox-virtual-environment/iso
+
+The {pve} installation media is a hybrid ISO image. It works in two ways:
+
+* An ISO image file ready to burn to a CD or DVD.
+
+* A raw sector (IMG) image file ready to copy to a USB flash drive (USB stick).
+
+Using a USB flash drive to install {pve} is the recommended way because it is
+the faster option.
+
+Prepare a USB Flash Drive as Installation Medium
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The flash drive needs to have at least 1 GB of storage available.
+
+NOTE: Do not use UNetbootin. It does not work with the {pve} installation image.
+
+IMPORTANT: Make sure that the USB flash drive is not mounted and does not
+contain any important data.
+
+
+Instructions for GNU/Linux
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On Unix-like operating system use the `dd` command to copy the ISO image to the
+USB flash drive. First find the correct device name of the USB flash drive (see
+below). Then run the `dd` command.
+
+----
+# dd bs=1M conv=fdatasync if=./proxmox-ve_*.iso of=/dev/XYZ
+----
+
+NOTE: Be sure to replace /dev/XYZ with the correct device name and adapt the
+input filename ('if') path.
+
+CAUTION: Be very careful, and do not overwrite the wrong disk!
+
+
+Find the Correct USB Device Name
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+There are two ways to find out the name of the USB flash drive. The first one is
+to compare the last lines of the `dmesg` command output before and after
+plugging in the flash drive. The second way is to compare the output of the
+`lsblk` command. Open a terminal and run:
+
+----
+# lsblk
+----
+
+Then plug in your USB flash drive and run the command again:
+
+----
+# lsblk
+----
+
+A new device will appear. This is the one you want to use. To be on the extra
+safe side check if the reported size matches your USB flash drive.
+
+
+Instructions for macOS
+~~~~~~~~~~~~~~~~~~~~~~
+
+Open the terminal (query Terminal in Spotlight).
+
+Convert the `.iso` file to `.dmg` format using the convert option of `hdiutil`,
+for example:
+
+----
+# hdiutil convert proxmox-ve_*.iso -format UDRW -o proxmox-ve_*.dmg
+----
+
+TIP: macOS tends to automatically add '.dmg' to the output file name.
+
+To get the current list of devices run the command:
+
+----
+# diskutil list
+----
+
+Now insert the USB flash drive and run this command again to determine which
+device node has been assigned to it. (e.g., /dev/diskX).
+
+----
+# diskutil list
+# diskutil unmountDisk /dev/diskX
+----
+
+NOTE: replace X with the disk number from the last command.
+
+----
+# sudo dd if=proxmox-ve_*.dmg bs=1M of=/dev/rdiskX
+----
+
+NOTE: 'rdiskX', instead of 'diskX', in the last command is intended. It will
+increase the write speed.
+
+Instructions for Windows
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using Etcher
+^^^^^^^^^^^^
+
+Etcher works out of the box. Download Etcher from https://etcher.io. It will
+guide you through the process of selecting the ISO and your USB flash drive.
+
+Using Rufus
+^^^^^^^^^^^
+
+Rufus is a more lightweight alternative, but you need to use the *DD mode* to
+make it work. Download Rufus from https://rufus.ie/. Either install it or use
+the portable version. Select the destination drive and the {pve} ISO file.
+
+IMPORTANT: Once you 'Start' you have to click 'No' on the dialog asking to
+download a different version of GRUB. In the next dialog select the 'DD' mode.
+
+ifdef::wiki[]
+Boot your Server from the USB Flash Drive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Connect the USB flash drive to your server and make sure that booting from USB
+is enabled (check your servers firmware settings). Then follow the steps in the
+xref:chapter_installation[installation wizard].
+
+endif::wiki[]
--
2.44.0



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [RFC PATCH docs-common 02/13] installation-media: adapt for common usage

[Christoph Heiss]

Small adaptions were necessary; mostly a trivial s/{pve}/{product}/g and
replacing the ISO URL with the {iso-url} variable.

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

diff --git a/installation-media.adoc b/installation-media.adoc
index a1c9402..bcef51c 100644
--- a/installation-media.adoc
+++ b/installation-media.adoc
@@ -1,27 +1,30 @@
 [[installation_prepare_media]]
 Prepare Installation Media
 --------------------------
+ifdef::pve[]
 ifdef::wiki[]
 :pve-toplevel:
 endif::wiki[]
+endif::pve[]

-Download the installer ISO image from: {website}en/downloads/proxmox-virtual-environment/iso
+Download the installer ISO image from: {iso-url}

-The {pve} installation media is a hybrid ISO image. It works in two ways:
+The {product} installation media is a hybrid ISO image. It works in two ways:

 * An ISO image file ready to burn to a CD or DVD.

 * A raw sector (IMG) image file ready to copy to a USB flash drive (USB stick).

-Using a USB flash drive to install {pve} is the recommended way because it is
-the faster option.
+Using a USB flash drive to install {product} is the recommended way because it
+is the faster option.

 Prepare a USB Flash Drive as Installation Medium
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 The flash drive needs to have at least 1 GB of storage available.

-NOTE: Do not use UNetbootin. It does not work with the {pve} installation image.
+NOTE: Do not use UNetbootin. It does not work with the {product} installation
+image.

 IMPORTANT: Make sure that the USB flash drive is not mounted and does not
 contain any important data.
@@ -35,7 +38,7 @@ USB flash drive. First find the correct device name of the USB flash drive (see
 below). Then run the `dd` command.

 ----
-# dd bs=1M conv=fdatasync if=./proxmox-ve_*.iso of=/dev/XYZ
+# dd bs=1M conv=fdatasync if=./proxmox-*.iso of=/dev/XYZ
 ----

 NOTE: Be sure to replace /dev/XYZ with the correct device name and adapt the
@@ -74,7 +77,7 @@ Convert the `.iso` file to `.dmg` format using the convert option of `hdiutil`,
 for example:

 ----
-# hdiutil convert proxmox-ve_*.iso -format UDRW -o proxmox-ve_*.dmg
+# hdiutil convert proxmox-*.iso -format UDRW -o proxmox-ve_*.dmg
 ----

 TIP: macOS tends to automatically add '.dmg' to the output file name.
@@ -96,7 +99,7 @@ device node has been assigned to it. (e.g., /dev/diskX).
 NOTE: replace X with the disk number from the last command.

 ----
-# sudo dd if=proxmox-ve_*.dmg bs=1M of=/dev/rdiskX
+# sudo dd if=proxmox-*.dmg bs=1M of=/dev/rdiskX
 ----

 NOTE: 'rdiskX', instead of 'diskX', in the last command is intended. It will
@@ -116,7 +119,7 @@ Using Rufus

 Rufus is a more lightweight alternative, but you need to use the *DD mode* to
 make it work. Download Rufus from https://rufus.ie/. Either install it or use
-the portable version. Select the destination drive and the {pve} ISO file.
+the portable version. Select the destination drive and the {product} ISO file.

 IMPORTANT: Once you 'Start' you have to click 'No' on the dialog asking to
 download a different version of GRUB. In the next dialog select the 'DD' mode.
--
2.44.0



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [RFC PATCH docs-common 03/13] partials: add installation flow from pve-docs

[Christoph Heiss]

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

diff --git a/partials/installation-flow.adoc b/partials/installation-flow.adoc
new file mode 100644
index 0000000..b796676
--- /dev/null
+++ b/partials/installation-flow.adoc
@@ -0,0 +1,170 @@
+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.
+
+TIP: Make sure that booting from the installation medium (for example, USB) is
+enabled in your server's firmware settings. Secure boot needs to be disabled
+when booting an installer prior to {pve} version 8.1.
+
+[thumbnail="screenshot/pve-grub-menu.png"]
+
+After choosing the correct entry (for example, 'Boot from USB') the {pve} menu
+will be displayed, and one of the following options can be selected:
+
+Install {pve} (Graphical)::
+
+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
+from the respective button. For example, `ALT + N` to press a `Next` button.
+
+Install {pve} (Terminal UI)::
+
+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 {pve} (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="screenshot/pve-tui-installer.png"]
+
+Both modes use the same code base for the actual installation process to
+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. See also
+xref:nomodeset_kernel_param[adding the `nomodeset` kernel parameter].
+
+Advanced Options: Install {pve} (Graphical, Debug Mode)::
+
+Starts the installation in debug mode. A console will be opened at several
+installation steps. This helps to debug the situation if something goes wrong.
+To exit a debug console, press `CTRL-D`. This option can be used to boot a live
+system with all basic tools available. You can use it, for example, to
+xref:chapter_zfs[repair a degraded ZFS 'rpool'] or fix the
+xref:sysboot[bootloader] for an existing {pve} setup.
+
+Advanced Options: Install {pve} (Terminal UI, Debug Mode)::
+
+Same as the graphical debug mode, but preparing the system to run the
+terminal-based installer instead.
+
+Advanced Options: Install {pve} (Serial Console Debug Mode)::
+
+Same the terminal-based debug mode, but additionally sets up the Linux kernel to
+use the (first) serial port of the machine for in- and output.
+
+Advanced Options: Rescue Boot::
+
+With this option you can boot an existing installation. It searches all attached
+hard disks. If it finds an existing installation, it boots directly into that
+disk using the Linux kernel from the ISO. This can be useful if there are
+problems with the bootloader (GRUB/`systemd-boot`) or the BIOS/UEFI is unable to
+read the boot block from the disk.
+
+Advanced Options: Test Memory (memtest86+)::
+
+Runs `memtest86+`. This is useful to check if the memory is functional and free
+of errors. Secure Boot must be turned off in the UEFI firmware setup utility to
+run this option.
+
+You normally select *Install {pve} (Graphical)* to start the installation.
+
+[thumbnail="screenshot/pve-select-target-disk.png"]
+
+The first step is to read our EULA (End User License Agreement). Following this,
+you can select the target hard disk(s) for the installation.
+
+CAUTION: By default, the whole server is used and all existing data is removed.
+Make sure there is no important data on the server before proceeding with the
+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 xref:advanced_lvm_options[below]).
+
+{pve} 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 xref:advanced_zfs_options[`Advanced Options`].
+
+WARNING: ZFS on top of any hardware RAID is not supported and can result in data
+loss.
+
+[thumbnail="screenshot/pve-select-location.png"]
+
+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="screenshot/pve-set-password.png", float="left"]
+
+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, 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).
+
+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.
+
+[thumbnail="screenshot/pve-setup-network.png"]
+
+All those notification mails will be sent to the specified email address.
+
+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="screenshot/pve-installation.png", float="left"]
+
+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 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="screenshot/pve-install-summary.png"]
+
+Copying the packages usually takes several minutes, mostly depending on the
+speed of the installation medium and the target disk performance.
+
+When copying and setting up the packages has finished, you can reboot the
+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
+xref:install_minimal_requirements[minimum requirements].
+
+If the installation is still not working, look at the
+xref:getting_help[how to get help chapter].
--
2.44.0



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [RFC PATCH docs-common 04/13] partials: installation-flow: adapt from pve-docs

[Christoph Heiss]

A trivial s/{pve}/{product}/g again and a additional
s/screenshot\/pve-/screenshot\//g to fix the screenshot paths.

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 partials/installation-flow.adoc | 47 +++++++++++++++++----------------
 1 file changed, 24 insertions(+), 23 deletions(-)

diff --git a/partials/installation-flow.adoc b/partials/installation-flow.adoc
index b796676..9a7d1b3 100644
--- a/partials/installation-flow.adoc
+++ b/partials/installation-flow.adoc
@@ -7,14 +7,14 @@ Please insert the xref:installation_prepare_media[prepared installation media]

 TIP: Make sure that booting from the installation medium (for example, USB) is
 enabled in your server's firmware settings. Secure boot needs to be disabled
-when booting an installer prior to {pve} version 8.1.
+when booting an installer prior to {product} version 8.1.

-[thumbnail="screenshot/pve-grub-menu.png"]
+[thumbnail="screenshot/grub-menu.png"]

-After choosing the correct entry (for example, 'Boot from USB') the {pve} menu
-will be displayed, and one of the following options can be selected:
+After choosing the correct entry (for example, 'Boot from USB') the {product}
+menu will be displayed, and one of the following options can be selected:

-Install {pve} (Graphical)::
+Install {product} (Graphical)::

 Starts the normal installation.

@@ -22,20 +22,20 @@ 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
 from the respective button. For example, `ALT + N` to press a `Next` button.

-Install {pve} (Terminal UI)::
+Install {product} (Terminal UI)::

 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 {pve} (Terminal UI, Serial Console)::
+Install {product} (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="screenshot/pve-tui-installer.png"]
+[thumbnail="screenshot/tui-installer.png"]

 Both modes use the same code base for the actual installation process to
 benefit from more than a decade of bug fixes and ensure feature parity.
@@ -44,21 +44,21 @@ TIP: The 'Terminal UI' option can be used in case the graphical installer does
 not work correctly, due to e.g. driver issues. See also
 xref:nomodeset_kernel_param[adding the `nomodeset` kernel parameter].

-Advanced Options: Install {pve} (Graphical, Debug Mode)::
+Advanced Options: Install {product} (Graphical, Debug Mode)::

 Starts the installation in debug mode. A console will be opened at several
 installation steps. This helps to debug the situation if something goes wrong.
 To exit a debug console, press `CTRL-D`. This option can be used to boot a live
 system with all basic tools available. You can use it, for example, to
 xref:chapter_zfs[repair a degraded ZFS 'rpool'] or fix the
-xref:sysboot[bootloader] for an existing {pve} setup.
+xref:sysboot[bootloader] for an existing {product} setup.

-Advanced Options: Install {pve} (Terminal UI, Debug Mode)::
+Advanced Options: Install {product} (Terminal UI, Debug Mode)::

 Same as the graphical debug mode, but preparing the system to run the
 terminal-based installer instead.

-Advanced Options: Install {pve} (Serial Console Debug Mode)::
+Advanced Options: Install {product} (Serial Console Debug Mode)::

 Same the terminal-based debug mode, but additionally sets up the Linux kernel to
 use the (first) serial port of the machine for in- and output.
@@ -77,9 +77,9 @@ Runs `memtest86+`. This is useful to check if the memory is functional and free
 of errors. Secure Boot must be turned off in the UEFI firmware setup utility to
 run this option.

-You normally select *Install {pve} (Graphical)* to start the installation.
+You normally select *Install {product} (Graphical)* to start the installation.

-[thumbnail="screenshot/pve-select-target-disk.png"]
+[thumbnail="screenshot/select-target-disk.png"]

 The first step is to read our EULA (End User License Agreement). Following this,
 you can select the target hard disk(s) for the installation.
@@ -93,15 +93,16 @@ 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 xref:advanced_lvm_options[below]).

-{pve} 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 xref:advanced_zfs_options[`Advanced Options`].
+{product} 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
+xref:advanced_zfs_options[`Advanced Options`].

 WARNING: ZFS on top of any hardware RAID is not supported and can result in data
 loss.

-[thumbnail="screenshot/pve-select-location.png"]
+[thumbnail="screenshot/select-location.png"]

 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
@@ -110,7 +111,7 @@ 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="screenshot/pve-set-password.png", float="left"]
+[thumbnail="screenshot/set-password.png", float="left"]

 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
@@ -132,7 +133,7 @@ For example:

 - Error messages from periodic 'cron' jobs.

-[thumbnail="screenshot/pve-setup-network.png"]
+[thumbnail="screenshot/setup-network.png"]

 All those notification mails will be sent to the specified email address.

@@ -142,7 +143,7 @@ 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="screenshot/pve-installation.png", float="left"]
+[thumbnail="screenshot/installation.png", float="left"]

 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
@@ -152,7 +153,7 @@ 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="screenshot/pve-install-summary.png"]
+[thumbnail="screenshot/install-summary.png"]

 Copying the packages usually takes several minutes, mostly depending on the
 speed of the installation medium and the target disk performance.
--
2.44.0



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[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@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



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [RFC PATCH docs-common 06/13] partials: advanced-installation: adapt from pve-docs

[Christoph Heiss]

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

diff --git a/partials/advanced-installation.adoc b/partials/advanced-installation.adoc
index ed2709f..271533b 100644
--- a/partials/advanced-installation.adoc
+++ b/partials/advanced-installation.adoc
@@ -2,9 +2,9 @@
 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:
+The installer creates a Volume Group (VG) called +{product-short}+, 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`::

@@ -43,8 +43,8 @@ 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.
++{product-short}+. 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).
@@ -109,16 +109,16 @@ following command:

 [[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
+On the {product} bootloader menu, navigate to 'Install {product} (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.

--
2.44.0



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [RFC PATCH docs 07/13] gitmodules: add proxmox-docs-common

[Christoph Heiss]

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 .gitmodules         | 3 +++
 proxmox-docs-common | 1 +
 2 files changed, 4 insertions(+)
 create mode 100644 .gitmodules
 create mode 160000 proxmox-docs-common

diff --git a/.gitmodules b/.gitmodules
new file mode 100644
index 0000000..eff8adf
--- /dev/null
+++ b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "proxmox-docs-common"]
+	path = proxmox-docs-common
+	url = ../proxmox-docs-common
diff --git a/proxmox-docs-common b/proxmox-docs-common
new file mode 160000
index 0000000..a042676
--- /dev/null
+++ b/proxmox-docs-common
@@ -0,0 +1 @@
+Subproject commit a042676729ea0b87a03844eb4c468028bb45f55d
-- 
2.44.0



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [RFC PATCH docs 08/13] scan-adoc-refs: enable building pages from proxmox-docs-common/ subdir

[Christoph Heiss]

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 Makefile                   |  6 ++++--
 asciidoc/asciidoc-pve.conf |  2 ++
 pve-doc-generator.mk.in    |  6 ++++++
 scan-adoc-refs             | 25 ++++++++++++++++---------
 4 files changed, 28 insertions(+), 11 deletions(-)

diff --git a/Makefile b/Makefile
index 801a2a3..5b14e3d 100644
--- a/Makefile
+++ b/Makefile
@@ -26,9 +26,11 @@ all: index.html
 verify-images:
 	for i in ./images/screenshot/*.png; do ./png-verify.pl $$i; done
 
-ADOC_SOURCES_GUESS=$(filter-out %-synopsis.adoc %-opts.adoc %-table.adoc, $(wildcard *.adoc))
+ADOC_WILDCARD_SOURCES := *.adoc proxmox-docs-common/*.adoc proxmox-docs-common/partials/*.adoc
+ADOC_SOURCES_GUESS=$(filter-out %-synopsis.adoc %-opts.adoc %-table.adoc, $(wildcard $(ADOC_WILDCARD_SOURCES)))
+
 .pve-doc-depends link-refs.json: $(ADOC_SOURCES_GUESS) scan-adoc-refs
-	./scan-adoc-refs *.adoc --depends .pve-doc-depends.tmp > link-refs.json.tmp
+	./scan-adoc-refs $(ADOC_WILDCARD_SOURCES) --depends .pve-doc-depends.tmp > link-refs.json.tmp
 	@cmp --quiet .pve-doc-depends .pve-doc-depends.tmp || mv .pve-doc-depends.tmp .pve-doc-depends
 	@cmp --quiet link-refs.json link-refs.json.tmp || mv link-refs.json.tmp link-refs.json
 
diff --git a/asciidoc/asciidoc-pve.conf b/asciidoc/asciidoc-pve.conf
index 0c28298..47139b8 100644
--- a/asciidoc/asciidoc-pve.conf
+++ b/asciidoc/asciidoc-pve.conf
@@ -3,6 +3,8 @@
 proxmoxGmbh=Proxmox Server Solutions GmbH
 copyright=Proxmox Server Solutions GmbH
 pve=Proxmox VE
+product=Proxmox VE
+product-short=pve
 pricing-url=https://proxmox.com/en/proxmox-virtual-environment/pricing
 website=https://www.proxmox.com/
 forum-url=https://forum.proxmox.com/
diff --git a/pve-doc-generator.mk.in b/pve-doc-generator.mk.in
index 77fd4f6..a733966 100644
--- a/pve-doc-generator.mk.in
+++ b/pve-doc-generator.mk.in
@@ -71,9 +71,15 @@ endif
 %-plain.html: %.adoc ${PVE_COMMON_DOC_SOURCES}
 	${ASCIIDOC_PVE} compile-wiki -o $@ $*.adoc
 
+%-plain.html: proxmox-docs-common/%.adoc ${PVE_COMMON_DOC_SOURCES}
+	${ASCIIDOC_PVE} compile-wiki -o $@ proxmox-docs-common/$*.adoc
+
 chapter-%.html: %.adoc ${PVE_COMMON_DOC_SOURCES}
 	${ASCIIDOC_PVE} compile-chapter -o $@ $*.adoc
 
+chapter-%.html: proxmox-docs-common/%.adoc ${PVE_COMMON_DOC_SOURCES}
+	${ASCIIDOC_PVE} compile-chapter -o $@ proxmox-docs-common/$*.adoc
+
 %.1: %.adoc %.1-synopsis.adoc ${PVE_COMMON_DOC_SOURCES}
 	${ASCIIDOC_PVE} compile-man -o $@ $*.adoc
 	test -z "$${PVE_DOC_INSTANTVIEW}" || man -l $@
diff --git a/scan-adoc-refs b/scan-adoc-refs
index 9252701..fd74c20 100755
--- a/scan-adoc-refs
+++ b/scan-adoc-refs
@@ -5,6 +5,8 @@ use warnings;
 use Getopt::Long;
 use IO::File;
 use JSON;
+use Cwd qw(abs_path);
+use File::Spec;
 
 use Data::Dumper;
 
@@ -19,6 +21,7 @@ my $environments = {
     wiki => 1,
     manvolnum => 1,
     pvelogo => 0, # ignore
+    pve => 0,
 };
 
 my $fileinfo = {};
@@ -76,6 +79,12 @@ sub pop_environment {
 sub register_include {
     my ($filename, $include_filename, $env_list) = @_;
 
+    # get containing directory of the file that includes ..
+    my $reldir = (File::Spec->splitpath($filename))[1];
+    # .. and resolve the included filename relative to that
+    $include_filename = abs_path(File::Spec->join($reldir, $include_filename))
+	if $reldir;
+
     foreach my $e (@$env_list) {
 	$fileinfo->{include}->{$e}->{$filename}->{$include_filename} = 1;
     }
@@ -99,6 +108,7 @@ sub register_title {
 
     # fixme: what about other macros?
     $title =~ s/\{pve\}/Proxmox VE/g;
+    $title =~ s/\{product\}/Proxmox VE/g;
     $title =~ s!http://\S+\[(.*?)\]!$1!g;
 
     # register document title (onyl once)
@@ -269,23 +279,19 @@ foreach my $e (@$start_env) {
     my $toplevel_hash = $fileinfo->{toplevel}->{$e};
     foreach my $fn (sort keys %$toplevel_hash) {
 	my $mansection = $fileinfo->{mansection}->{manvolnum}->{$fn};
+	my $realfn = $fn;
+	$realfn =~ s/^proxmox-docs-common\///;
+	$realfn =~ s/\.adoc$//;
+
 	if ($e eq 'wiki') {
-	    my $realfn = $fn;
-	    $realfn =~ s/\.adoc$//;
 	    if (defined($mansection) && ($mansection == 5)) {
 		$realfn .= ".$mansection";
 	    }
 	    $realfn = "$realfn-plain.html";
-	    $fileinfo->{outfile}->{$e}->{$fn} = $realfn;
 	} elsif ($e eq 'manvolnum') {
-	    my $realfn = $fn;
-	    $realfn =~ s/\.adoc$//;
 	    die "toplevel file '$fn' is not marked as manual page!" if !$mansection;
 	    $realfn .= ".$mansection";
-	    $fileinfo->{outfile}->{$e}->{$fn} = $realfn;
 	} elsif ($e eq 'default') {
-	    my $realfn = $fn;
-	    $realfn =~ s/\.adoc$//;
 	    if (defined($mansection) && ($mansection == 5)) {
 		$realfn .= ".$mansection";
 		$realfn = "$realfn.html";
@@ -297,8 +303,9 @@ foreach my $e (@$start_env) {
 		    $realfn = "$realfn.html";
 		}
 	    }
-	    $fileinfo->{outfile}->{$e}->{$fn} = $realfn;
 	}
+
+	$fileinfo->{outfile}->{$e}->{$fn} = $realfn;
     }
 }
 
-- 
2.44.0



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [RFC PATCH docs 09/13] images: strip `pve-` prefix from screenshots used in common docs

[Christoph Heiss]

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 .../{pve-grub-menu.png => grub-menu.png}          | Bin
 .../{pve-grub-menu.ppm => grub-menu.ppm}          | Bin
 ...ve-install-summary.png => install-summary.png} | Bin
 ...ve-install-summary.ppm => install-summary.ppm} | Bin
 .../{pve-installation.png => installation.png}    | Bin
 .../{pve-installation.ppm => installation.ppm}    | Bin
 ...ve-select-location.png => select-location.png} | Bin
 ...ve-select-location.ppm => select-location.ppm} | Bin
 ...ect-target-disk.png => select-target-disk.png} | Bin
 ...ect-target-disk.ppm => select-target-disk.ppm} | Bin
 .../{pve-set-password.png => set-password.png}    | Bin
 .../{pve-set-password.ppm => set-password.ppm}    | Bin
 .../{pve-setup-network.png => setup-network.png}  | Bin
 .../{pve-setup-network.ppm => setup-network.ppm}  | Bin
 .../{pve-tui-installer.png => tui-installer.png}  | Bin
 .../{pve-tui-installer.ppm => tui-installer.ppm}  | Bin
 png-verify.pl                                     |  14 ++++++++------
 17 files changed, 8 insertions(+), 6 deletions(-)
 rename images/screenshot/{pve-grub-menu.png => grub-menu.png} (100%)
 rename images/screenshot/{pve-grub-menu.ppm => grub-menu.ppm} (100%)
 rename images/screenshot/{pve-install-summary.png => install-summary.png} (100%)
 rename images/screenshot/{pve-install-summary.ppm => install-summary.ppm} (100%)
 rename images/screenshot/{pve-installation.png => installation.png} (100%)
 rename images/screenshot/{pve-installation.ppm => installation.ppm} (100%)
 rename images/screenshot/{pve-select-location.png => select-location.png} (100%)
 rename images/screenshot/{pve-select-location.ppm => select-location.ppm} (100%)
 rename images/screenshot/{pve-select-target-disk.png => select-target-disk.png} (100%)
 rename images/screenshot/{pve-select-target-disk.ppm => select-target-disk.ppm} (100%)
 rename images/screenshot/{pve-set-password.png => set-password.png} (100%)
 rename images/screenshot/{pve-set-password.ppm => set-password.ppm} (100%)
 rename images/screenshot/{pve-setup-network.png => setup-network.png} (100%)
 rename images/screenshot/{pve-setup-network.ppm => setup-network.ppm} (100%)
 rename images/screenshot/{pve-tui-installer.png => tui-installer.png} (100%)
 rename images/screenshot/{pve-tui-installer.ppm => tui-installer.ppm} (100%)

diff --git a/images/screenshot/pve-grub-menu.png b/images/screenshot/grub-menu.png
similarity index 100%
rename from images/screenshot/pve-grub-menu.png
rename to images/screenshot/grub-menu.png
diff --git a/images/screenshot/pve-grub-menu.ppm b/images/screenshot/grub-menu.ppm
similarity index 100%
rename from images/screenshot/pve-grub-menu.ppm
rename to images/screenshot/grub-menu.ppm
diff --git a/images/screenshot/pve-install-summary.png b/images/screenshot/install-summary.png
similarity index 100%
rename from images/screenshot/pve-install-summary.png
rename to images/screenshot/install-summary.png
diff --git a/images/screenshot/pve-install-summary.ppm b/images/screenshot/install-summary.ppm
similarity index 100%
rename from images/screenshot/pve-install-summary.ppm
rename to images/screenshot/install-summary.ppm
diff --git a/images/screenshot/pve-installation.png b/images/screenshot/installation.png
similarity index 100%
rename from images/screenshot/pve-installation.png
rename to images/screenshot/installation.png
diff --git a/images/screenshot/pve-installation.ppm b/images/screenshot/installation.ppm
similarity index 100%
rename from images/screenshot/pve-installation.ppm
rename to images/screenshot/installation.ppm
diff --git a/images/screenshot/pve-select-location.png b/images/screenshot/select-location.png
similarity index 100%
rename from images/screenshot/pve-select-location.png
rename to images/screenshot/select-location.png
diff --git a/images/screenshot/pve-select-location.ppm b/images/screenshot/select-location.ppm
similarity index 100%
rename from images/screenshot/pve-select-location.ppm
rename to images/screenshot/select-location.ppm
diff --git a/images/screenshot/pve-select-target-disk.png b/images/screenshot/select-target-disk.png
similarity index 100%
rename from images/screenshot/pve-select-target-disk.png
rename to images/screenshot/select-target-disk.png
diff --git a/images/screenshot/pve-select-target-disk.ppm b/images/screenshot/select-target-disk.ppm
similarity index 100%
rename from images/screenshot/pve-select-target-disk.ppm
rename to images/screenshot/select-target-disk.ppm
diff --git a/images/screenshot/pve-set-password.png b/images/screenshot/set-password.png
similarity index 100%
rename from images/screenshot/pve-set-password.png
rename to images/screenshot/set-password.png
diff --git a/images/screenshot/pve-set-password.ppm b/images/screenshot/set-password.ppm
similarity index 100%
rename from images/screenshot/pve-set-password.ppm
rename to images/screenshot/set-password.ppm
diff --git a/images/screenshot/pve-setup-network.png b/images/screenshot/setup-network.png
similarity index 100%
rename from images/screenshot/pve-setup-network.png
rename to images/screenshot/setup-network.png
diff --git a/images/screenshot/pve-setup-network.ppm b/images/screenshot/setup-network.ppm
similarity index 100%
rename from images/screenshot/pve-setup-network.ppm
rename to images/screenshot/setup-network.ppm
diff --git a/images/screenshot/pve-tui-installer.png b/images/screenshot/tui-installer.png
similarity index 100%
rename from images/screenshot/pve-tui-installer.png
rename to images/screenshot/tui-installer.png
diff --git a/images/screenshot/pve-tui-installer.ppm b/images/screenshot/tui-installer.ppm
similarity index 100%
rename from images/screenshot/pve-tui-installer.ppm
rename to images/screenshot/tui-installer.ppm
diff --git a/png-verify.pl b/png-verify.pl
index d345ff6..a316e1b 100755
--- a/png-verify.pl
+++ b/png-verify.pl
@@ -5,12 +5,14 @@ use warnings;
 use File::Basename;
 
 my $installer_images = {
-    'pve-grub-menu.png' => 1,
-    'pve-installation.png' => 1,
-    'pve-select-location.png' => 1,
-    'pve-select-target-disk.png' => 1,
-    'pve-set-password.png' => 1,
-    'pve-setup-network.png' => 1,
+    'grub-menu.png' => 1,
+    'install-summary.png' => 1,
+    'installation.png' => 1,
+    'select-location.png' => 1,
+    'select-target-disk.png' => 1,
+    'set-password.png' => 1,
+    'setup-network.png' => 1,
+    'tui-installer.png' => 1,
 };
 
 my $infile = shift ||
-- 
2.44.0



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [RFC PATCH docs 10/13] asciidoc: conf: add iso-url variable

[Christoph Heiss]

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 asciidoc/asciidoc-pve.conf | 1 +
 1 file changed, 1 insertion(+)

diff --git a/asciidoc/asciidoc-pve.conf b/asciidoc/asciidoc-pve.conf
index 47139b8..faa190a 100644
--- a/asciidoc/asciidoc-pve.conf
+++ b/asciidoc/asciidoc-pve.conf
@@ -6,6 +6,7 @@ pve=Proxmox VE
 product=Proxmox VE
 product-short=pve
 pricing-url=https://proxmox.com/en/proxmox-virtual-environment/pricing
+iso-url=https://proxmox.com/downloads/proxmox-virtual-environment
 website=https://www.proxmox.com/
 forum-url=https://forum.proxmox.com/
 forum=https://forum.proxmox.com/[Proxmox VE Community Forum]
-- 
2.44.0



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [RFC PATCH docs 11/13] installation-media: move to common docs

[Christoph Heiss]

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 pve-installation-media.adoc | 132 ------------------------------------
 pve-installation.adoc       |   2 +-
 2 files changed, 1 insertion(+), 133 deletions(-)
 delete mode 100644 pve-installation-media.adoc

diff --git a/pve-installation-media.adoc b/pve-installation-media.adoc
deleted file mode 100644
index a1c9402..0000000
--- a/pve-installation-media.adoc
+++ /dev/null
@@ -1,132 +0,0 @@
-[[installation_prepare_media]]
-Prepare Installation Media
---------------------------
-ifdef::wiki[]
-:pve-toplevel:
-endif::wiki[]
-
-Download the installer ISO image from: {website}en/downloads/proxmox-virtual-environment/iso
-
-The {pve} installation media is a hybrid ISO image. It works in two ways:
-
-* An ISO image file ready to burn to a CD or DVD.
-
-* A raw sector (IMG) image file ready to copy to a USB flash drive (USB stick).
-
-Using a USB flash drive to install {pve} is the recommended way because it is
-the faster option.
-
-Prepare a USB Flash Drive as Installation Medium
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The flash drive needs to have at least 1 GB of storage available.
-
-NOTE: Do not use UNetbootin. It does not work with the {pve} installation image.
-
-IMPORTANT: Make sure that the USB flash drive is not mounted and does not
-contain any important data.
-
-
-Instructions for GNU/Linux
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-On Unix-like operating system use the `dd` command to copy the ISO image to the
-USB flash drive. First find the correct device name of the USB flash drive (see
-below). Then run the `dd` command.
-
-----
-# dd bs=1M conv=fdatasync if=./proxmox-ve_*.iso of=/dev/XYZ
-----
-
-NOTE: Be sure to replace /dev/XYZ with the correct device name and adapt the
-input filename ('if') path.
-
-CAUTION: Be very careful, and do not overwrite the wrong disk!
-
-
-Find the Correct USB Device Name
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-There are two ways to find out the name of the USB flash drive. The first one is
-to compare the last lines of the `dmesg` command output before and after
-plugging in the flash drive. The second way is to compare the output of the
-`lsblk` command. Open a terminal and run:
-
-----
-# lsblk
-----
-
-Then plug in your USB flash drive and run the command again:
-
-----
-# lsblk
-----
-
-A new device will appear. This is the one you want to use. To be on the extra
-safe side check if the reported size matches your USB flash drive.
-
-
-Instructions for macOS
-~~~~~~~~~~~~~~~~~~~~~~
-
-Open the terminal (query Terminal in Spotlight).
-
-Convert the `.iso` file to `.dmg` format using the convert option of `hdiutil`,
-for example:
-
-----
-# hdiutil convert proxmox-ve_*.iso -format UDRW -o proxmox-ve_*.dmg
-----
-
-TIP: macOS tends to automatically add '.dmg' to the output file name.
-
-To get the current list of devices run the command:
-
-----
-# diskutil list
-----
-
-Now insert the USB flash drive and run this command again to determine which
-device node has been assigned to it. (e.g., /dev/diskX).
-
-----
-# diskutil list
-# diskutil unmountDisk /dev/diskX
-----
-
-NOTE: replace X with the disk number from the last command.
-
-----
-# sudo dd if=proxmox-ve_*.dmg bs=1M of=/dev/rdiskX
-----
-
-NOTE: 'rdiskX', instead of 'diskX', in the last command is intended. It will
-increase the write speed.
-
-Instructions for Windows
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Using Etcher
-^^^^^^^^^^^^
-
-Etcher works out of the box. Download Etcher from https://etcher.io. It will
-guide you through the process of selecting the ISO and your USB flash drive.
-
-Using Rufus
-^^^^^^^^^^^
-
-Rufus is a more lightweight alternative, but you need to use the *DD mode* to
-make it work. Download Rufus from https://rufus.ie/. Either install it or use
-the portable version. Select the destination drive and the {pve} ISO file.
-
-IMPORTANT: Once you 'Start' you have to click 'No' on the dialog asking to
-download a different version of GRUB. In the next dialog select the 'DD' mode.
-
-ifdef::wiki[]
-Boot your Server from the USB Flash Drive
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Connect the USB flash drive to your server and make sure that booting from USB
-is enabled (check your servers firmware settings). Then follow the steps in the
-xref:chapter_installation[installation wizard].
-
-endif::wiki[]
diff --git a/pve-installation.adoc b/pve-installation.adoc
index 274d9ad..f492ad0 100644
--- a/pve-installation.adoc
+++ b/pve-installation.adoc
@@ -29,7 +29,7 @@ ifndef::wiki[]
 
 include::pve-system-requirements.adoc[]
 
-include::pve-installation-media.adoc[]
+include::proxmox-docs-common/installation-media.adoc[]
 
 endif::wiki[]
 
-- 
2.44.0



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [RFC PATCH docs 12/13] installation: use new 'installation-flow' partial from common docs

[Christoph Heiss]

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 pve-installation.adoc | 172 +-----------------------------------------
 1 file changed, 1 insertion(+), 171 deletions(-)

diff --git a/pve-installation.adoc b/pve-installation.adoc
index f492ad0..2f4642e 100644
--- a/pve-installation.adoc
+++ b/pve-installation.adoc
@@ -52,177 +52,7 @@ The installer ISO image includes the following:
 
 * Web-based management interface
 
-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.
-
-TIP: Make sure that booting from the installation medium (for example, USB) is
-enabled in your server's firmware settings. Secure boot needs to be disabled
-when booting an installer prior to {pve} version 8.1.
-
-[thumbnail="screenshot/pve-grub-menu.png"]
-
-After choosing the correct entry (for example, 'Boot from USB') the {pve} menu
-will be displayed, and one of the following options can be selected:
-
-Install {pve} (Graphical)::
-
-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
-from the respective button. For example, `ALT + N` to press a `Next` button.
-
-Install {pve} (Terminal UI)::
-
-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 {pve} (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="screenshot/pve-tui-installer.png"]
-
-Both modes use the same code base for the actual installation process to
-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. See also
-xref:nomodeset_kernel_param[adding the `nomodeset` kernel parameter].
-
-Advanced Options: Install {pve} (Graphical, Debug Mode)::
-
-Starts the installation in debug mode. A console will be opened at several
-installation steps. This helps to debug the situation if something goes wrong.
-To exit a debug console, press `CTRL-D`. This option can be used to boot a live
-system with all basic tools available. You can use it, for example, to
-xref:chapter_zfs[repair a degraded ZFS 'rpool'] or fix the
-xref:sysboot[bootloader] for an existing {pve} setup.
-
-Advanced Options: Install {pve} (Terminal UI, Debug Mode)::
-
-Same as the graphical debug mode, but preparing the system to run the
-terminal-based installer instead.
-
-Advanced Options: Install {pve} (Serial Console Debug Mode)::
-
-Same the terminal-based debug mode, but additionally sets up the Linux kernel to
-use the (first) serial port of the machine for in- and output.
-
-Advanced Options: Rescue Boot::
-
-With this option you can boot an existing installation. It searches all attached
-hard disks. If it finds an existing installation, it boots directly into that
-disk using the Linux kernel from the ISO. This can be useful if there are
-problems with the bootloader (GRUB/`systemd-boot`) or the BIOS/UEFI is unable to
-read the boot block from the disk.
-
-Advanced Options: Test Memory (memtest86+)::
-
-Runs `memtest86+`. This is useful to check if the memory is functional and free
-of errors. Secure Boot must be turned off in the UEFI firmware setup utility to
-run this option.
-
-You normally select *Install {pve} (Graphical)* to start the installation.
-
-[thumbnail="screenshot/pve-select-target-disk.png"]
-
-The first step is to read our EULA (End User License Agreement). Following this,
-you can select the target hard disk(s) for the installation.
-
-CAUTION: By default, the whole server is used and all existing data is removed.
-Make sure there is no important data on the server before proceeding with the
-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 xref:advanced_lvm_options[below]).
-
-{pve} 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 xref:advanced_zfs_options[`Advanced Options`].
-
-WARNING: ZFS on top of any hardware RAID is not supported and can result in data
-loss.
-
-[thumbnail="screenshot/pve-select-location.png"]
-
-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="screenshot/pve-set-password.png", float="left"]
-
-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, 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).
-
-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.
-
-[thumbnail="screenshot/pve-setup-network.png"]
-
-All those notification mails will be sent to the specified email address.
-
-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="screenshot/pve-installation.png", float="left"]
-
-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 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="screenshot/pve-install-summary.png"]
-
-Copying the packages usually takes several minutes, mostly depending on the
-speed of the installation medium and the target disk performance.
-
-When copying and setting up the packages has finished, you can reboot the
-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
-xref:install_minimal_requirements[minimum requirements].
-
-If the installation is still not working, look at the
-xref:getting_help[how to get help chapter].
-
+include::proxmox-docs-common/partials/installation-flow.adoc[]
 
 Accessing the Management Interface Post-Installation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.44.0



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] [RFC PATCH docs 13/13] installation: use new 'advanced-installation' partial from common docs

[Christoph Heiss]

Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
---
 pve-installation.adoc | 126 +-----------------------------------------
 1 file changed, 1 insertion(+), 125 deletions(-)

diff --git a/pve-installation.adoc b/pve-installation.adoc
index 2f4642e..0a0dc76 100644
--- a/pve-installation.adoc
+++ b/pve-installation.adoc
@@ -78,131 +78,7 @@ web interface for further configuration.
 
 . Check your xref:chapter_pve_firewall[Firewall settings].
 
-[[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.
+include::proxmox-docs-common/partials/advanced-installation.adoc[]
 
 ifndef::wiki[]
 
-- 
2.44.0



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [pve-devel] [RFC PATCH docs-common 01/13] installation-media: move page from pve-docs here

[Aaron Lauterer]

On  2024-04-19  11:05, Christoph Heiss wrote:
> Small adaptions were necessary; mostly a s/{pve}/{product}/g and
> replacing the ISO URL with the {iso-url} variable.

except there are still plenty of `{pve}`s in there?

another thing looking at this patch, how do we handle product specifics?
having a ton of variables that are set according to the product, might 
be cumbersome.

Most likely something like `ifdef:product-pve` and so forth would be useful.

some situations I spotted where we would probably need it in this 
patched marked below:

> 
> Signed-off-by: Christoph Heiss <c.heiss@proxmox.com>
> ---
>   installation-media.adoc | 132 ++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 132 insertions(+)
>   create mode 100644 installation-media.adoc
> 
> diff --git a/installation-media.adoc b/installation-media.adoc
> new file mode 100644
> index 0000000..a1c9402
> --- /dev/null
> +++ b/installation-media.adoc
> @@ -0,0 +1,132 @@
> +[[installation_prepare_media]]
> +Prepare Installation Media
> +--------------------------
> +ifdef::wiki[]
> +:pve-toplevel:
> +endif::wiki[]
> +
> +Download the installer ISO image from: {website}en/downloads/proxmox-virtual-environment/iso

^actual download link for each product

> +
> +The {pve} installation media is a hybrid ISO image. It works in two ways:
> +
> +* An ISO image file ready to burn to a CD or DVD.
> +
> +* A raw sector (IMG) image file ready to copy to a USB flash drive (USB stick).
> +
> +Using a USB flash drive to install {pve} is the recommended way because it is
> +the faster option.
> +
> +Prepare a USB Flash Drive as Installation Medium
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The flash drive needs to have at least 1 GB of storage available.
> +
> +NOTE: Do not use UNetbootin. It does not work with the {pve} installation image.
> +
> +IMPORTANT: Make sure that the USB flash drive is not mounted and does not
> +contain any important data.
> +
> +
> +Instructions for GNU/Linux
> +~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +On Unix-like operating system use the `dd` command to copy the ISO image to the
> +USB flash drive. First find the correct device name of the USB flash drive (see
> +below). Then run the `dd` command.
> +
> +----
> +# dd bs=1M conv=fdatasync if=./proxmox-ve_*.iso of=/dev/XYZ

^ useful example, though this one could also be helped with by putting 
the 've_' part into the glob as well
> +----
> +
> +NOTE: Be sure to replace /dev/XYZ with the correct device name and adapt the
> +input filename ('if') path.
> +
> +CAUTION: Be very careful, and do not overwrite the wrong disk!
> +
> +
> +Find the Correct USB Device Name
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +There are two ways to find out the name of the USB flash drive. The first one is
> +to compare the last lines of the `dmesg` command output before and after
> +plugging in the flash drive. The second way is to compare the output of the
> +`lsblk` command. Open a terminal and run:
> +
> +----
> +# lsblk
> +----
> +
> +Then plug in your USB flash drive and run the command again:
> +
> +----
> +# lsblk
> +----
> +
> +A new device will appear. This is the one you want to use. To be on the extra
> +safe side check if the reported size matches your USB flash drive.
> +
> +
> +Instructions for macOS
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +Open the terminal (query Terminal in Spotlight).
> +
> +Convert the `.iso` file to `.dmg` format using the convert option of `hdiutil`,
> +for example:
> +
> +----
> +# hdiutil convert proxmox-ve_*.iso -format UDRW -o proxmox-ve_*.dmg
> +----
> +
> +TIP: macOS tends to automatically add '.dmg' to the output file name.
> +
> +To get the current list of devices run the command:
> +
> +----
> +# diskutil list
> +----
> +
> +Now insert the USB flash drive and run this command again to determine which
> +device node has been assigned to it. (e.g., /dev/diskX).
> +
> +----
> +# diskutil list
> +# diskutil unmountDisk /dev/diskX
> +----
> +
> +NOTE: replace X with the disk number from the last command.
> +
> +----
> +# sudo dd if=proxmox-ve_*.dmg bs=1M of=/dev/rdiskX
> +----
> +
> +NOTE: 'rdiskX', instead of 'diskX', in the last command is intended. It will
> +increase the write speed.
> +
> +Instructions for Windows
> +~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Using Etcher
> +^^^^^^^^^^^^
> +
> +Etcher works out of the box. Download Etcher from https://etcher.io. It will
> +guide you through the process of selecting the ISO and your USB flash drive.
> +
> +Using Rufus
> +^^^^^^^^^^^
> +
> +Rufus is a more lightweight alternative, but you need to use the *DD mode* to
> +make it work. Download Rufus from https://rufus.ie/. Either install it or use
> +the portable version. Select the destination drive and the {pve} ISO file.
> +
> +IMPORTANT: Once you 'Start' you have to click 'No' on the dialog asking to
> +download a different version of GRUB. In the next dialog select the 'DD' mode.
> +
> +ifdef::wiki[]
> +Boot your Server from the USB Flash Drive
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Connect the USB flash drive to your server and make sure that booting from USB
> +is enabled (check your servers firmware settings). Then follow the steps in the
> +xref:chapter_installation[installation wizard].

Aligning chapter references will also be some work, especially if we 
want to keep old direct links still working.

> +
> +endif::wiki[]
> --
> 2.44.0
> 
> 
> 
> _______________________________________________
> pve-devel mailing list
> pve-devel@lists.proxmox.com
> https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
> 
> 


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

Re: [pve-devel] [RFC PATCH docs-common 01/13] installation-media: move page from pve-docs here

[Christoph Heiss]

Thanks for the review!

On Fri, Apr 19, 2024 at 12:51:07PM +0200, Aaron Lauterer wrote:
>
>
> On  2024-04-19  11:05, Christoph Heiss wrote:
> > Small adaptions were necessary; mostly a s/{pve}/{product}/g and
> > replacing the ISO URL with the {iso-url} variable.
>
> except there are still plenty of `{pve}`s in there?

Oh right, that is a leftover from splitting the patch into to separate
commits. I'll remove that with the next revision. Sorry for the
confusion.

>
> another thing looking at this patch, how do we handle product specifics?
> having a ton of variables that are set according to the product, might be
> cumbersome.
>
> Most likely something like `ifdef:product-pve` and so forth would be useful.

Depending on the amount of specifics, that's were splitting sections out
into partials (into proxmox-docs-common) and then including them into
the main page (in the product-specific docs) come into play.

E.g. the installer page is a good example where I tried to apply this
pattern. Some things like the installer flow and advanced options are
sharable, there are still some sections that are specific to e.g. PVE.

As for e.g. the `{pve}` macro, there is now simply a `{product}` (and
`{product-short}` macro, which already handles most other, trivial
differences.

But overall, that is definitely a point to discuss further and improve
upon incrementally as pages/sections are moved and pain points are
discovered, IMO.

>
> some situations I spotted where we would probably need it in this patched
> marked below:

All of these should be fixed up/adapted in the next patch in the series.
I've split them into two for review sake, where the first is a 1:1 copy
and the next patch then adapts it.

[..]
> > +
> > +ifdef::wiki[]
> > +Boot your Server from the USB Flash Drive
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +Connect the USB flash drive to your server and make sure that booting from USB
> > +is enabled (check your servers firmware settings). Then follow the steps in the
> > +xref:chapter_installation[installation wizard].
>
> Aligning chapter references will also be some work, especially if we want to
> keep old direct links still working.

That's a very good point, thanks for noticing!
I'll definitely keep note of that, but probably would deal with that as
we come to that.

>
> > +
> > +endif::wiki[]
> > --
> > 2.44.0
> >
> >
> >
> > _______________________________________________
> > pve-devel mailing list
> > pve-devel@lists.proxmox.com
> > https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
> >
> >


_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel