Installation
============
-{pmg} is based on Debian and comes with an installation CD-ROM
-which includes a complete Debian ("buster" for version 6.x) system as
-well as all necessary {pmg} packages.
+{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.
-The installer just asks you a few questions, then partitions the local
-disk(s), installs all required packages, and configures the system
-including a basic network setup. You can get a fully functional system
-within a few minutes. This is the preferred and recommended
-installation method.
+TIP: See the xref:faq-support-table[support table in the FAQ] for the
+relationship between {pmg} releases and Debian releases.
-Alternatively, {pmg} can be installed on top of an existing Debian
-system. This option is only recommended for advanced users since
-it requires more detailed knowledge about {pmg} and Debian.
+The installer will guide you through the setup, allowing you to partition the local
+disk(s), apply basic system configurations (for example, timezone, 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} Installation CD-ROM
-----------------------------------
-You can download the ISO from https://www.proxmox.com. It includes the
-following:
+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,
- ext3, xfs or ZFS and installs the operating system.
+ XFS or ZFS and installs the operating system
* Linux kernel
* Postfix MTA, ClamAV, Spamassassin and the {pmg} toolset
-* Web based management interface for using the toolset
+* Web-based management interface for using the toolset
+
-Please burn the downloaded ISO image to a CD or create a
-xref:create_bootable_usb[bootable USB stick].
+Please insert the xref:installation_prepare_media[prepared installation media]
+(for example, USB flash drive or CD-ROM) and boot from it.
-Then insert the installation CD-ROM on the physical host where you want
-to install {pmg} and boot from that drive. Immediately afterwards you
-can choose the following menu options:
+TIP: Make sure that booting from the installation medium (for example, USB) is
+enabled in your servers firmware settings.
+
+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} (Debug mode)::
-Start installation in debug mode. It opens a shell console at several
-installation steps, so that you can debug things if something goes
-wrong. Please press `CTRL-D` to exit those debug consoles and continue
-installation. This option is mostly for developers and not meant for
-general use.
+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.
Rescue Boot::
image::images/installer/pmg-select-target-disk.png[]
-First step ist to read our EULA (End User License Agreement). After
-that you get prompted to select the target hard disk(s).
+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.
-NOTE: By default, the complete server is used and all existing data is
-removed.
+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 `ext3`,
-`ext4` or `xfs` as file system, and offers additional option to
+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 <<advanced_lvm_options,below>>)
-If you have more than one disk, you can also use ZFS as file system.
-ZFS supports several software RAID levels, so this is specially useful
+If you have more than one disk, you can also use ZFS as a file system.
+ZFS supports several software RAID levels, which is particularly useful
if you do not have a hardware RAID controller. The `Options` button
-lets you select the ZFS RAID level, and you can choose disks there.
+lets you choose the ZFS RAID level and select which disks will be used.
image::images/installer/pmg-select-location.png[]
-The next page just ask for basic configuration options like your
-location, the time zone and keyboard layout. The location is used to
-select a download server near you to speedup updates. The installer is
-usually able to auto detect those setting, so you only need to change
-them in rare situations when auto detection fails, or when you want to
-use some special keyboard layout not commonly used in your country.
+The next page asks for basic configuration options like your
+location, timezone, 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.
image::images/installer/pmg-set-password.png[]
or past) and biographical information (e.g., ID numbers, ancestors' names or
dates).
-It is sometimes necessary to send notification to the system
-administrator, for example:
+It is sometimes necessary to send notification to the system administrator, for
+example:
- Information about available package updates.
-- Error messages from periodic CRON jobs.
+- Error messages from periodic cron jobs.
-All those notification mails will be sent to the specified email
-address.
+All those notification mails will be sent to the specified email address.
image::images/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 installation.
+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[]
-If 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 back and edit any settings.
+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
+back and edit any settings.
-If you press `Install` now, the installation process starts to format disks,
-and copies packages to the target disk(s).
+After clicking `Install`, the installer will begin to format and copy packages
+to the target disk(s).
image::images/installer/pmg-installation.png[]
-Copying packages usually takes a few minutes. Please wait until that is
-finished, then reboot the server.
+Copying the packages usually takes several minutes. When this is
+finished, you can reboot the server.
-Further configuration is done via the Proxmox web interface.
+Further configuration is done via the {pmg} web interface:
[thumbnail="pmg-gui-login-window.png"]
-Just point your browser to the IP address given during installation
+. Point your browser to the IP address given during the installation
(https://youripaddress:8006).
-. Login and upload subscription key.
+. Log in and upload your subscription key.
+
-NOTE: Default login is "root" and the root password is
-defined during the installation process.
+NOTE: The default login is "root", and the password is the one chosen during the
+installation.
. Check the IP configuration and hostname.
-. Check and save the Time Zone.
+. Check the timezone.
. Check your xref:firewall_settings[Firewall settings].
-. Configure {pmg} to forward the incoming SMTP traffic to your Mail
+. Configure {pmg} to forward the incoming SMTP traffic to your mail
server ('Configuration/Mail Proxy/Default Relay') - 'Default
-Relay' is your e-mail server.
+Relay' is your email server.
-. Configure your e-mail server to send all outgoing messages through
+. 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].
-If the installation succeeds you have to route all your incoming and
-outgoing e-mail traffic to the Mail Gateway. For incoming traffic you
+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 e-mail server configuration.
+traffic you need to change the existing email server configuration.
[[advanced_lvm_options]]
`hdsize`::
-Defines the total HD size to be used. This way you can save free
-space on the HD for further partitioning (i.e. for an additional PV
-and VG on the same hard disk that can be used for LVM storage).
+Defines the total disk size to be used. This way you can save free
+space on the disk for further partitioning (i.e. for an additional PV
+and VG on the same 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`.
+installed memory. The minimum is 4 GB and the maximum is 8 GB. The resulting
+value cannot be greater than `hdsize/8`.
`minfree`::
-Defines the amount of free space left in LVM volume group `pmg`.
-With more than 128GB storage available the default is 16GB, else `hdsize/8`
-will be used.
+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).
want to use ZFS. A good calculation is 4GB plus 1GB RAM for each TB
RAW disk space.
-ZFS also provides the feature to use a fast SSD drive as write cache. The
+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
-installation using the following command:
+the installation using the following command:
zpool add <pool-name> log </dev/path_to_fast_ssd>
-include::pmg-usbstick.adoc[]
-
-
[[pmg_install_on_debian]]
Install {pmg} on Debian
-----------------------
{pmg} ships as a set of Debian packages, so you can install it
on top of a normal Debian installation. After configuring the
-repositories, you need to run:
+xref:pmg_package_repositories[package repositories], you need to run:
[source,bash]
----
-apt-get update
-apt-get install proxmox-mailgateway
+apt update
+apt install proxmox-mailgateway
----
-Installing on top of an existing Debian installation looks easy, but
-it presumes that you have correctly installed the base system, and you
+Installing on top of an existing Debian installation seems easy, but
+it assumes that you have correctly installed the base system, and you
know how you want to configure and use the local storage. Network
configuration is also completely up to you.
[[pmg_install_on_debian_container]]
-Install {pmg} as Linux Container Appliance
-------------------------------------------
+Install {pmg} as a Linux Container Appliance
+--------------------------------------------
-The full functionality of {pmg} can also run on top of a Debian-based LXC
+{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. It does not depend on any Linux Kernel, firmware, or components
+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.
-A ready-to-use appliance template is available through the
-https://www.proxmox.com/proxmox-ve[Proxmox VE] appliance manager in the `mail`
-section, so if you already use Proxmox VE you can setup a {pmg} instance in a
-minute.
+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.
-NOTE: It's recommended to use a static network configuration. If DHCP should be
-used ensure that the container can always lease the same IP, for example, by
-reserving one with the containers network MAC address.
+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 also install this on top of a normal Debian installation.
-After configuring the repositories, you need to run:
+Additionally, you can install this on top of a container-based Debian
+installation. After configuring the
+xref:pmg_package_repositories[package repositories], you need to run:
[source,bash]
----
-apt-get update
-apt-get install proxmox-mailgateway-container
+apt update
+apt install proxmox-mailgateway-container
----
-
[[pmg_package_repositories]]
Package Repositories
--------------------
-All {debian} based systems use
-https://en.wikipedia.org/wiki/Advanced_Packaging_Tool[APT] as package
-management tool. The list of repositories is defined in
-`/etc/apt/sources.list` and `.list` files found inside
-`/etc/apt/sources.d/`. Updates can be installed directly using
-`apt-get`, or via the GUI.
+{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` and in `.list`
+files placed in `/etc/apt/sources.list.d/`.
+
+Repository Management
+^^^^^^^^^^^^^^^^^^^^^
+
+[thumbnail="pmg-gui-admin-repositories.png"]
-Apt `sources.list` files list one package repository per line, with
-the most preferred source listed first. Empty lines are ignored, and a
-`#` character anywhere on a line marks the remainder of that line as a
-comment. The information available from the configured sources is
-acquired by `apt-get update`.
+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.
+
+Sources.list
+^^^^^^^^^^^^
+
+In a `sources.list` file, each line defines a package repository. The preferred
+source must come first. Empty lines are ignored. A `#` character anywhere on a
+line marks the remainder of that line as a comment. The available packages from
+a repository are acquired by running `apt update`. Updates can be installed
+directly using `apt`, or via the GUI (Administration -> Updates).
.File `/etc/apt/sources.list`
----
-deb http://ftp.debian.org/debian buster main contrib
-
-deb http://ftp.debian.org/debian buster-updates main contrib
+# basic Debian repositories:
+deb http://ftp.debian.org/debian bullseye main contrib
+deb http://ftp.debian.org/debian bullseye-updates main contrib
# security updates
-deb http://security.debian.org/debian-security buster/updates main contrib
+deb http://security.debian.org/debian-security bullseye-security main contrib
+
+# Proxmox Mail Gateway repo required too - see below!
----
-// FIXME for 7.0: change security update suite to bullseye-security
-In addition, {pmg} provides three different package repositories.
+{pmg} provides three different package repositories.
{pmg} Enterprise Repository
.File `/etc/apt/sources.list.d/pmg-enterprise.list`
----
-deb https://enterprise.proxmox.com/debian/pmg buster pmg-enterprise
+deb https://enterprise.proxmox.com/debian/pmg bullseye pmg-enterprise
----
As soon as updates are available, the `root@pam` user is notified via
-email about the available new packages. On the GUI, the change-log of
+email about the newly available packages. From the GUI, the change-log of
each package can be viewed (if available), showing all details of the
-update. So you will never miss important security fixes.
+update. Thus, you will never miss important security fixes.
-Please note that and you need a valid subscription key to access this
-repository. We offer different support levels, and you can find further
-details at {pricing-url}.
+Please note that you need a valid subscription key to access this
+repository. We offer different support levels, which you can find further
+details about at {pricing-url}.
NOTE: You can disable this repository by commenting out the above line
-using a `#` (at the start of the line). This prevents error messages
+using a `#` (at the start of the line). This prevents error messages,
if you do not have a subscription key. Please configure the
-`pmg-no-subscription` repository in that case.
+`pmg-no-subscription` repository in this case.
{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. Its not recommended to run on production servers, as these
+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`.
+We recommend configuring this repository in `/etc/apt/sources.list`.
.File `/etc/apt/sources.list`
----
-deb http://ftp.debian.org/debian buster main contrib
+deb http://ftp.debian.org/debian bullseye main contrib
+deb http://ftp.debian.org/debian bullseye-updates main contrib
+
+# security updates
+deb http://security.debian.org/debian-security bullseye-security main contrib
# PMG pmg-no-subscription repository provided by proxmox.com,
# NOT recommended for production use
-deb http://download.proxmox.com/debian/pmg buster pmg-no-subscription
-
-# security updates
-deb http://security.debian.org/debian-security buster/updates main contrib
+deb http://download.proxmox.com/debian/pmg bullseye pmg-no-subscription
----
{pmg} Test Repository
~~~~~~~~~~~~~~~~~~~~~
-Finally, there is a repository called `pmgtest`. This one contains the
-latest packages and is heavily used by developers to test new
-features. As usual, you can configure this using
+Finally, there is a repository called `pmgtest`. This contains the
+latest packages, and is heavily used by developers to test new
+features. As with before, you can configure this using
`/etc/apt/sources.list` by adding the following line:
.sources.list entry for `pmgtest`
----
-deb http://download.proxmox.com/debian/pmg buster pmgtest
+deb http://download.proxmox.com/debian/pmg bullseye pmgtest
----
-WARNING: the `pmgtest` repository should (as the name implies) only be used
+WARNING: the `pmgtest` repository should only be used
for testing new features or bug fixes.
SecureApt
~~~~~~~~~
-We use GnuPG to sign the `Release` files inside those repositories,
-and APT uses that signatures to verify that all packages are from a
+We use GnuPG to sign the `Release` files inside these repositories,
+and APT uses these signatures to verify that all packages are from a
trusted source.
-The key used for verification is already installed if you install from
-our installation CD. If you install by other means, you can manually
+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:
- # wget http://download.proxmox.com/debian/proxmox-ve-release-6.x.gpg -O /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
+----
+ # wget https://enterprise.proxmox.com/debian/proxmox-release-bullseye.gpg -O /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg
+----
-Please verify the checksum afterwards:
+Verify the checksum afterwards with the `sha512sum` CLI tool:
----
-# sha512sum /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
-acca6f416917e8e11490a08a1e2842d500b3a5d9f322c6319db0927b2901c3eae23cfb5cd5df6facf2b57399d3cfa52ad7769ebdd75d9b204549ca147da52626 /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
+# sha512sum /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg
+7fb03ec8a1675723d2853b84aa4fdb49a46a3bb72b9951361488bfd19b29aab0a789a4f8c7406e71a69aabbc727c936d3549731c4659ffa1a08f44db8fdcebfa /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg
----
-or
+or the `md5sum` CLI tool:
----
-# md5sum /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
-f3f6c5a3a67baf38ad178e5ff1ee270c /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
+# md5sum /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg
+bcc35c7173e0845c0d6ad6470b70f50e /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg
----
+Other Repository Sources
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+.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
+----
+
+Following this, you can install the required packages with:
+
+----
+apt update
+apt install libclamunrar p7zip-rar
+----
projects / pmg-docs.git / blobdiff