* 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.
+
+Advanced Options: Install {pmg} (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 repair a
+degraded ZFS 'rpool' or fix the bootloader for an existing {pmg} setup.
+
+Advanced Options: Install {pmg} (Terminal UI, Debug Mode)::
+
+Same as the graphical debug mode, but preparing the system to run the
+terminal-based installer instead.
-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} (Serial Console Debug Mode)::
-Rescue Boot::
+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.
-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: Rescue Boot::
-Test Memory::
+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.
-Runs `memtest86+`. This is useful to check if your memory is
-functional and error free.
+Advanced Options: Test Memory (memtest86+)::
-You normally select *Install {pmg}* to start the installation.
+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.
-image::images/installer/pmg-select-target-disk.png[]
+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", float="left"]
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"]
You then need to specify an email address and the superuser (root)
password. The password must have at least 5 characters, but we highly
All those notification mails will be sent to the specified email address.
-image::images/installer/pmg-setup-network.png[]
+[thumbnail="installer/pmg-setup-network.png"]
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.
+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].
+
Further configuration is done via the {pmg} web interface:
-[thumbnail="pmg-gui-login-window.png"]
+[thumbnail="screenshot/pmg-gui-login-window.png"]
. Point your browser to the IP address given during the installation
(https://youripaddress:8006).
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>
+---
+
+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.
- zpool add <pool-name> log </dev/path_to_fast_ssd>
+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-ve[Proxmox VE] appliance manager, so if you
-already use Proxmox VE, you can set up a {pmg} instance in minutes.
+https://www.proxmox.com/proxmox-virtual-environment/overview[Proxmox VE]
+appliance manager, so if you already use Proxmox VE, you can set up a {pmg}
+instance in minutes.
NOTE: It's recommended to use a static network configuration. If DHCP must be
used, ensure that the container always leases the same IP, for example, by
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'
.File `/etc/apt/sources.list`
----
# basic Debian repositories:
-deb http://ftp.debian.org/debian bullseye main contrib
-deb http://ftp.debian.org/debian bullseye-updates main contrib
+deb http://deb.debian.org/debian bookworm main contrib
+deb http://deb.debian.org/debian bookworm-updates main contrib
# security updates
-deb http://security.debian.org/debian-security bullseye-security main contrib
+deb http://security.debian.org/debian-security bookworm-security main contrib
# Proxmox Mail Gateway repo required too - see below!
----
.File `/etc/apt/sources.list.d/pmg-enterprise.list`
----
-deb https://enterprise.proxmox.com/debian/pmg bullseye pmg-enterprise
+deb https://enterprise.proxmox.com/debian/pmg bookworm pmg-enterprise
----
As soon as updates are available, the `root@pam` user is notified via
.File `/etc/apt/sources.list`
----
-deb http://ftp.debian.org/debian bullseye main contrib
-deb http://ftp.debian.org/debian bullseye-updates main contrib
+deb http://ftp.debian.org/debian bookworm main contrib
+deb http://ftp.debian.org/debian bookworm-updates main contrib
# security updates
-deb http://security.debian.org/debian-security bullseye-security main contrib
+deb http://security.debian.org/debian-security bookworm-security main contrib
# PMG pmg-no-subscription repository provided by proxmox.com,
# NOT recommended for production use
-deb http://download.proxmox.com/debian/pmg bullseye pmg-no-subscription
+deb http://download.proxmox.com/debian/pmg bookworm pmg-no-subscription
----
.sources.list entry for `pmgtest`
----
-deb http://download.proxmox.com/debian/pmg bullseye pmgtest
+deb http://download.proxmox.com/debian/pmg bookworm pmgtest
----
WARNING: the `pmgtest` repository should only be used
The key used for verification is already installed, if you install from
our installation CD. If you install via another means, you can manually
-download the key with:
+download the key by executing the following command as root user:
----
- # wget https://enterprise.proxmox.com/debian/proxmox-release-bullseye.gpg -O /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg
+ # wget https://enterprise.proxmox.com/debian/proxmox-release-bookworm.gpg -O /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg
----
Verify the checksum afterwards with the `sha512sum` CLI tool:
----
-# sha512sum /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg
-7fb03ec8a1675723d2853b84aa4fdb49a46a3bb72b9951361488bfd19b29aab0a789a4f8c7406e71a69aabbc727c936d3549731c4659ffa1a08f44db8fdcebfa /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg
+# sha512sum /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg
+7da6fe34168adc6e479327ba517796d4702fa2f8b4f0a9833f5ea6e6b48f6507a6da403a274fe201595edc86a84463d50383d07f64bdde2e3658108db7d6dc87 /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg
----
or the `md5sum` CLI tool:
----
-# md5sum /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg
-bcc35c7173e0845c0d6ad6470b70f50e /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg
+# md5sum /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg
+41558dc019ef90bd0f6067644a51cf5b /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg
----
-Other Repository Sources
-~~~~~~~~~~~~~~~~~~~~~~~~
+Debian Non-Free Repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~
Certain software cannot be made available in the `main` and `contrib`
areas of the {debian} archives, since it does not adhere to the Debian
* `libclamunrar` for detecting viruses in RAR archives.
-.Additional sources.list entry for `non-free`
-----
-deb http://deb.debian.org/debian/ bullseye non-free
-deb http://security.debian.org/debian-security bullseye-security non-free
-deb http://deb.debian.org/debian/ bullseye-updates non-free
-----
+To enable the `non-free` component, run `editor /etc/apt/sources.list` and
+append `non-free` to the end of each `.debian.org` repository line.
Following this, you can install the required packages with:
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