* 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.
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 servers firmware settings.
+enabled in your server's firmware settings. Secure boot needs to be disabled
+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
will be displayed, and one of the following options can be selected:
-image::images/installer/pmg-grub-menu.png[]
-
-Install {pmg}::
+Install {pmg} (Graphical)::
Start normal installation.
-Install {pmg} (Debug mode)::
+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 {pmg} (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 {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
+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.
-Start installation in debug mode. This opens a shell console at various stages
-throughout the installation, so that you can debug issues, if something goes
-wrong. You can press `CTRL-D` to exit the debug console and continue the
-installation. This option is mostly for developers and not meant for general
-use.
+Advanced Options: Install {pmg} (Graphical, Debug Mode)::
-Rescue Boot::
+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 repair a
+degraded ZFS 'rpool' or fix the bootloader for an existing {pmg} setup.
-This option allows you to boot an existing installation. It searches
-all attached hard disks and, if it finds an existing installation,
-boots directly into that disk using the existing Linux kernel. This
-can be useful if there are problems with the boot block (grub), or the
-BIOS is unable to read the boot block from the disk.
+Advanced Options: Install {pmg} (Terminal UI, Debug Mode)::
-Test Memory::
+Same as the graphical debug mode, but preparing the system to run the
+terminal-based installer instead.
-Runs `memtest86+`. This is useful to check if your memory is
-functional and error free.
+Advanced Options: Install {pmg} (Serial Console Debug Mode)::
-You normally select *Install {pmg}* to start the installation.
+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.
-image::images/installer/pmg-select-target-disk.png[]
+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 {pmg} (Graphical)* to start the installation.
+
+[thumbnail="installer/pmg-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.
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.
-image::images/installer/pmg-select-location.png[]
+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
change them in rare situations when auto-detection fails, or when you want to
use a keyboard layout not commonly used in your country.
-image::images/installer/pmg-set-password.png[]
+[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:
-- Use a minimum password length of 12 to 14 characters.
+- Use a minimum password length of at least 12 characters.
- Include lowercase and uppercase alphabetic characters, numbers and symbols.
- Error messages from periodic cron jobs.
-All those notification mails will be sent to the specified email address.
+[thumbnail="installer/pmg-setup-network.png"]
-image::images/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.
-image::images/installer/pmg-summary.png[]
+[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
After clicking `Install`, the installer will begin to format and copy packages
to the target disk(s).
-image::images/installer/pmg-installation.png[]
+[thumbnail="installer/pmg-summary.png"]
-Copying the packages usually takes several minutes. When this is
-finished, you can reboot the server.
+Copying the packages usually takes several minutes, mostly depending on the
+speed of the installation medium and the target disk performance.
-Further configuration is done via the {pmg} web interface:
+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.
-[thumbnail="pmg-gui-login-window.png"]
+.Installation Failure
-. Point your browser to the IP address given during the installation
-(https://youripaddress:8006).
+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].
-. Log in and upload your subscription key.
-+
-NOTE: The default login is "root", and the password is the one chosen during the
-installation.
+If the installation is still not working, look at the xref:getting_help[how to
+get help chapter].
+
+
+Accessing the Management Interface Post-Installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[thumbnail="screenshot/pmg-gui-login-window.png"]
+
+After a succesful installation and reboot of the system you can use the {pmg}
+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.
+
+. 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
+ repositories to get updates for security fixes, bug fixes, and new features.
. Check the IP configuration and hostname.
ZFS Performance Tips
~~~~~~~~~~~~~~~~~~~~
-ZFS uses a lot of memory, so it is best to add additional RAM if you
-want to use ZFS. A good calculation is 4GB plus 1GB RAM for each TB
+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 also provides the ability to use a fast SSD drive as write cache. The
-write cache is called the ZFS Intent Log (ZIL). You can add that after
-the installation using the following command:
+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>
+----
+# zpool add <pool-name> log </dev/path_to_fast_ssd>
+----
+
+Adding the `nomodeset` Kernel Parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Problems may arise on very old or very new hardware due to graphics drivers. If
+the installation hangs during the boot. In that case, 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 {pmg} bootloader menu, navigate to 'Install {pmg} (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.
[[pmg_install_on_debian]]
Install {pmg} on Debian
instance. In order to keep the set of installed software, and thus the
necessary updates minimal, you can use the `proxmox-mailgateway-container`
meta-package. This does not depend on any Linux kernel, firmware, or components
-used for booting from bare-metal, like grub2.
+used for booting from bare-metal, like GRUB.
A ready-to-use appliance template is available through the `mail` section of the
https://www.proxmox.com/proxmox-virtual-environment/overview[Proxmox VE]
Repository Management
^^^^^^^^^^^^^^^^^^^^^
-[thumbnail="pmg-gui-admin-repositories.png"]
+[thumbnail="screenshot/pmg-gui-admin-repositories.png"]
Since {pmg} 7.0 you can check the repository state in the web interface. The
'Dashboard' shows a high level status overview, while the separate 'Repository'
apt update
apt install libclamunrar p7zip-rar
----
+
+
+[[pmg_debian_firmware_repo]]
+Debian Firmware Repository
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Starting with Debian Bookworm ({pmg} 8) non-free firmware (as defined by
+https://www.debian.org/social_contract#guidelines[DFSG]) has been moved to the
+newly created Debian repository component `non-free-firmware`.
+
+Enable this repository if you want to set up
+xref:pmg_firmware_cpu[Early OS Microcode Updates] or need additional
+xref:pmg_firmware_runtime_files[Runtime Firmware Files] not already included in
+the pre-installed package `pve-firmware`.
+
+To be able to install packages from this component, run
+`editor /etc/apt/sources.list`, append `non-free-firmware` to the end of each
+`.debian.org` repository line and run `apt update`.
projects / pmg-docs.git / blobdiff