Installing {pmg}
================

{pmg} is based on Debian. This is why the install disk images (ISO files)
provided by Proxmox include a complete Debian system as well as all necessary
{pmg} packages.

TIP: See the xref:faq-support-table[support table in the FAQ] for the
relationship between {pmg} releases and Debian releases.

The installer will guide you through the setup, allowing you to partition the
local disk(s), apply basic system configurations (for example, time zone,
language, network) and install all required packages. This process should not
take more than a few minutes. Installing with the provided ISO is the
recommended method for new and existing users.

Alternatively, {pmg} can be installed on top of an existing Debian system. This
option is only recommended for advanced users because detailed knowledge about
{pmg} is required.

include::pmg-installation-media.adoc[]

[[pmg_install_iso]]
Using the {pmg} Installer
-------------------------

The installer ISO image includes the following:

* Complete operating system (Debian Linux, 64-bit)

* The {pmg} installer, which partitions the hard drive(s) with ext4,
  XFS or ZFS and installs the operating system

* {pmg} Linux kernel

* Postfix MTA, ClamAV, Spamassassin and the {pmg} toolset

* Web-based management interface for using the toolset

NOTE: All existing data on the 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 {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:

Install {pmg} (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 {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.

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

Install {pmg} (Terminal UI, Serial Console)::

Starts the terminal-mode installation wizard, additionally setting up the Linux
kernel to use the (first) serial port of the machine for in- and output. This
can be used if the machine is completely headless and only has a serial console
available.

Advanced Options: Install {pmg} (Graphical, Debug Mode)::

Starts the installation in debug mode. A console will be opened at several
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.

Advanced Options: Install {pmg} (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 {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.

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]).

{pmg} can also be installed on ZFS. As ZFS offers several software RAID levels,
this is an option for systems that don't have a hardware RAID controller. The
target disks must be selected in the `Options` dialog. More ZFS specific
settings can be changed under xref:advanced_zfs_options[`Advanced Options`].

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

[thumbnail="installer/pmg-select-location.png"]

The next page asks for basic configuration options like your location, time
zone, and keyboard layout. The location is used to select a nearby download
server, in order to increase the speed of updates. The installer is usually able
to auto-detect these settings, so you only need to change them in rare
situations when auto-detection fails, or when you want to use a keyboard layout
not commonly used in your country.

[thumbnail="installer/pmg-set-password.png", float="left"]

Next the password of the superuser (`root`) and an email address needs to be
specified. The password must consist of at least 8 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="installer/pmg-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="installer/pmg-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="installer/pmg-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].


Accessing the Management Interface Post-Installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[thumbnail="screenshot/pmg-gui-login-window.png"]

After a successful 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` (realm 'PAM') username and the password chosen during
installation.

. Upload your subscription key to gain access to the Enterprise repository.
  Otherwise, you will need to set up one of the public, less tested package
  repositories to get updates for security fixes, bug fixes, and new features.

. Check the IP configuration and hostname.

. Check the timezone.

. Check your xref:firewall_settings[Firewall settings].

. Configure {pmg} to forward the incoming SMTP traffic to your mail
server ('Configuration/Mail Proxy/Default Relay') - 'Default
Relay' is your email server.

. Configure your email server to send all outgoing messages through
your {pmg} ('Smart Host', port 26 by default).

For detailed deployment scenarios see chapter
xref:chapter_deployment[Planning for Deployment].

After the installation, you have to route all your incoming and
outgoing email traffic to {pmg}. For incoming traffic, you
have to configure your firewall and/or DNS settings. For outgoing
traffic you need to change the existing email server configuration.


[[advanced_lvm_options]]
Advanced LVM Configuration Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The installer creates a Volume Group (VG) called `pmg`, and additional Logical
Volumes (LVs) called `root`, `data`, and `swap`, if `ext4` or `xfs` is used. To
control the size of these volumes use:

`hdsize`::

Defines the total hard disk size to be used. This way you can reserve free space
on the hard disk for further partitioning (for example for an additional PV and
VG on the same hard disk that can be used for LVM storage).

`swapsize`::

Defines the size of the `swap` volume. The default is the size of the
installed memory. The minimum is 4 GB and the maximum is 8 GB. The resulting
value cannot be greater than `hdsize/8`.
+
NOTE: If set to `0`, no `swap` volume will be created.

`minfree`::

Defines the amount of free space that should be left in the LVM volume group
`pmg`. 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.

`ashift`::

Defines the `ashift` value for the created pool. The `ashift` needs to be set at
least to the sector-size of the underlying disks (2 to the power of `ashift` is
the sector-size), or any disk which might be put in the pool (for example the
replacement of a defective disk).

`compress`::

Defines whether compression is enabled for `rpool`.

`checksum`::

Defines which checksumming algorithm should be used for `rpool`.

`copies`::

Defines the `copies` parameter for `rpool`. Check the `zfs(8)` manpage for the
semantics, and why this does not replace redundancy on disk-level.

`hdsize`::

Defines the total hard disk size to be used. This is useful to save free space
on the hard disk(s) for further partitioning (for example to create a
swap-partition). `hdsize` is only honored for bootable disks, that is only the
first disk or mirror for RAID0, RAID1 or RAID10, and all disks in RAID-Z[123].

ZFS Performance Tips
~~~~~~~~~~~~~~~~~~~~

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

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, 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_unattended]]
Unattended Installation
-----------------------

It is possible to install {pmg} automatically in an unattended manner. This
enables you to fully automate the setup process with the ISO. Once the
installation is complete and the host has booted up, automation tools like
Ansible can be used to further configure the installation.

The necessary options for the installer must be provided in an answer file. This
file allows the use of filter rules to determine which disks and network cards
should be used.

To use the automated installation, it is first necessary to prepare an
installation ISO.
https://pve.proxmox.com/wiki/Automated_Installation[Visit our wiki] for more
details and information on the unattended installation.


[[pmg_install_on_debian]]
Install {pmg} on Debian
-----------------------

{pmg} ships as a set of Debian packages and can be installed on top of a
standard Debian installation.
xref:pmg_package_repositories[After configuring the repositories], you need
to run the following commands:

----
apt update
apt install proxmox-mailgateway
----

Installing on top of an existing Debian installation looks easy, but it presumes
that the base system has been installed correctly and that you know how you want
to configure and use the local storage. You also need to configure the network
manually.

NOTE: In general, this is not trivial, especially when LVM or ZFS is used.

[[pmg_install_on_debian_container]]
Install {pmg} as a Linux Container Appliance
--------------------------------------------

{pmg} can also run inside a Debian-based LXC
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 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]
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
reserving one with the container's network MAC address.

Additionally, you can install this on top of a container-based Debian
installation.
xref:pmg_package_repositories[After configuring the repositories], you need to
run:

----
apt update
apt install proxmox-mailgateway-container
----

[[pmg_package_repositories]]
Package Repositories
--------------------

{pmg} uses http://en.wikipedia.org/wiki/Advanced_Packaging_Tool[APT] as its
package management tool like any other Debian-based system.

Repositories in {pmg}
~~~~~~~~~~~~~~~~~~~~~

Repositories are a collection of software packages. They can be used to install
new software, but are also important to get new updates.

NOTE: You need valid Debian and Proxmox repositories to get the latest
security updates, bug fixes and new features.

APT Repositories are defined in the file `/etc/apt/sources.list` in the legacy
single-line format and in `.sources` files placed in `/etc/apt/sources.list.d/`
for the modern deb822 multi-line format, see
xref:pmg_install_apt_repo_formats[Repository Formats] for details.

Repository Management
^^^^^^^^^^^^^^^^^^^^^

[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'
panel (accessible via 'Administration') shows in-depth status and list of all
configured repositories.

Basic repository management, for example, activating or deactivating a
repository, is also supported.

[[pmg_install_apt_repo_formats]]
Repository Formats
^^^^^^^^^^^^^^^^^^

Package repositories can be configured in the source list
'/etc/apt/sources.list' and the files contained in '/etc/apt/sources.list.d/'.

There are two formats supported:

single line::

In a single-line `sources.list` file, each line defines a package repository.
Empty lines are ignored. A `#` character anywhere on a line marks the remainder
of that line as a comment.
This is the legacy format. Since Debian 13 Trixie apt will complain about using
this format. You can automatically migrate most repositories using the `apt
modernize-sources` command.

deb822::

In the multi-line format `repo.sources` file each entry consists of multiple
lines of key-value pairs. A file can include multiple entries by separating each
group with a blank line. This is the modern format.

Available Repositories

{pmg} provides three different package repositories in addition to requiring the
base Debian repositories.


Debian Base Repositories
~~~~~~~~~~~~~~~~~~~~~~~~

.File `/etc/apt/sources.list.d/debian.sources`
----
Types: deb deb-src
URIs: http://deb.debian.org/debian/
Suites: trixie trixie-updates
Components: main non-free-firmware
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg

Types: deb deb-src
URIs: http://security.debian.org/debian-security/
Suites: trixie-security
Components: main non-free-firmware
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg
----




[[pmg_enterprise_repository]]
{pmg} Enterprise Repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is the default, stable and recommended repository, available for
all {pmg} subscription users. It contains the most stable packages,
and is suitable for production use. The `pmg-enterprise` repository is
enabled by default:

.File `/etc/apt/sources.list.d/pmg-enterprise.sources`
----
Types: deb
URIs: https://enterprise.proxmox.com/debian/pmg
Suites: trixie
Components: pmg-enterprise
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
----

As soon as updates are available, the `root@pam` user is notified via email
about the newly available packages. From the GUI, the 'Changelog' button in the
GUI can be used to see more details about the selected update.
Thus, you will never miss important security fixes.

Please note that you need a valid subscription key to access the
`pmg-enterprise` repository. We offer different support levels, which you can
find further details about at {pricing-url}.

NOTE: You can disable this repository by adding an `Enabled: no` line to the
relevant entry in the file. This will prevent error messages if your host does
not have a subscription key. In that case, please configure the
`pmg-no-subscription` repository.

[[pmg_no_subscription_repository]]
{pmg} No-Subscription Repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As the name suggests, you do not need a subscription key to access
this repository. It can be used for testing and non-production
use. It's not recommended to use this on production servers, as these
packages are not always heavily tested and validated.

We recommend to configure this repository in
`/etc/apt/sources.list.d/proxmox.sources`.

.File `/etc/apt/sources.list.d/proxmox.sources`
----
Types: deb
URIs: http://download.proxmox.com/debian/pmg
Suites: trixie
Components: pmg-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
----

NOTE: Remember that you will always need the base Debian repositories in
addition to a {pmg} Proxmox repository.


[[pmg_test_repository]]
{pmg} Test Repository
~~~~~~~~~~~~~~~~~~~~~

This repository contains the latest packages and is primarily used by developers
to test new features. To configure it, add the following stanza to the file
`/etc/apt/sources.list.d/proxmox.sources`:

.File `/etc/apt/sources.list.d/proxmox.sources`
----
Types: deb
URIs: http://download.proxmox.com/debian/pmg
Suites: trixie
Components: pmg-test
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
----

WARNING: The `pmg-test` repository should (as the name implies) only be used for
testing new features or bug fixes.

{pmg} Debug Symbol Repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Debug symbol packages, named `<package>-dbgsym`, contain the detached debug
information for the matching binary package. They are not needed for normal
operation, but let tools such as `gdb`, `systemd-coredump` or `crash` produce
useful backtraces when analyzing a crash or hang. They are provided in a
dedicated repository, separate from the regular ones, for the Debian Bookworm
and Trixie based {pmg} releases (and newer). To configure it, add the following
line to `/etc/apt/sources.list`:

.sources.list entry for `pmg-dbgsym`
----
deb https://dbgsym.proxmox.com/debian/pmg bookworm pmg-dbgsym
----

After enabling the repository, install the `-dbgsym` package that matches the
binary you want to debug.

[[pmg_repos_secure_apt]]
SecureApt
~~~~~~~~~

The 'Release' files in the repositories are signed with GnuPG. APT is using
these signatures to verify that all packages are from a trusted source.

If you install {pmg} from an official ISO image, the key for verification is
already installed.

If you install {pmg} on top of Debian, download and install
the key with the following commands:

----
 # wget https://enterprise.proxmox.com/debian/proxmox-archive-keyring-trixie.gpg -O /usr/share/keyrings/proxmox-archive-keyring.gpg
----

NOTE: The `wget` command above adds the keyring for Proxmox releases based on
Debian Trixie. Once the `proxmox-archive-keyring` package is installed, it will
manage this file. At that point, the hashes below may no longer match the hashes
of this file, as keys for new Proxmox releases get added or removed. This is
intended, `apt` will ensure that only trusted keys are being used.
*Modifying this file is discouraged once `proxmox-archive-keyring` is installed.*

Verify the checksum afterwards with the `sha256sum` CLI tool:

----
# sha256sum /usr/share/keyrings/proxmox-archive-keyring.gpg
 136673be77aba35dcce385b28737689ad64fd785a797e57897589aed08db6e45 /usr/share/keyrings/proxmox-archive-keyring.gpg
----

or the `md5sum` CLI tool:

----
# md5sum /usr/share/keyrings/proxmox-archive-keyring.gpg
77c8b1166d15ce8350102ab1bca2fcbf /usr/share/keyrings/proxmox-archive-keyring.gpg
----

NOTE: Make sure the path you install the key to matches the `Signed-By:` lines
in your repository stanzas.

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
Free Software Guidelines (DFSG). These are distributed in the
{debian_nonfree_archive_area}. For {pmg} two packages from the `non-free` area
are needed in order to support the RAR archive format:

* `p7zip-rar` for matching xref:pmg_mailfilter_what[Archive Objects] in the
  xref:chapter_mailfilter[Rule system]

* `libclamunrar` for detecting viruses in RAR archives.

To enable the `non-free` component, run `editor /etc/apt/sources.list.d/debian.sources` 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.d/debian.sources`, append `non-free-firmware` to
the end of each `.debian.org` repository line and run `apt update`.
