4 {pmg} is based on Debian and comes with an installation CD-ROM
5 which includes a complete Debian ("buster" for version 6.x) system as
6 well as all necessary {pmg} packages.
8 The installer asks some questions, then partitions the local
9 disk(s), installs all required packages, and configures the system,
10 including a basic network setup. This gives you a fully functional system
11 within minutes. This is the preferred and recommended
14 Alternatively, {pmg} can be installed on top of an existing Debian
15 system. This option is only recommended for advanced users since
16 it requires more detailed knowledge about {pmg} and Debian.
18 include::pmg-installation-media.adoc[]
21 Using the {pmg} Installation CD-ROM
22 -----------------------------------
24 The installer ISO image includes the following:
26 * Complete operating system (Debian Linux, 64-bit)
28 * The {pmg} installer, which partitions the hard drive(s) with ext4,
29 xfs or ZFS and installs the operating system
33 * Postfix MTA, ClamAV, Spamassassin and the {pmg} toolset
35 * Web-based management interface for using the toolset
39 Please insert the xref:installation_prepare_media[prepared installation media]
40 (for example, USB flash drive or CD-ROM) and boot from it.
42 TIP: Make sure that booting from the installation medium (for example, USB) is
43 enabled in your servers firmware settings.
45 After choosing the correct entry (for example, Boot from USB) the {pmg} menu
46 will be displayed, and one of the following options can be selected:
48 image::images/installer/pmg-grub-menu.png[]
52 Start normal installation.
54 Install {pmg} (Debug mode)::
56 Start installation in debug mode. This opens a shell console at various stages
57 throughout the installation, so that you can debug issues, if something goes
58 wrong. You can press `CTRL-D` to exit the debug console and continue the
59 installation. This option is mostly for developers and not meant for general
64 This option allows you to boot an existing installation. It searches
65 all attached hard disks and, if it finds an existing installation,
66 boots directly into that disk using the existing Linux kernel. This
67 can be useful if there are problems with the boot block (grub), or the
68 BIOS is unable to read the boot block from the disk.
72 Runs `memtest86+`. This is useful to check if your memory is
73 functional and error free.
75 You normally select *Install {pmg}* to start the installation.
77 image::images/installer/pmg-select-target-disk.png[]
79 The first step is to read our EULA (End User License Agreement). Following
80 this, you can select the target hard disk(s) for the installation.
82 CAUTION: By default, the whole server is used and all existing data is removed.
83 Make sure there is no important data on the server before proceeding with the
86 The `Options` button lets you select the target file system, which
87 defaults to `ext4`. The installer uses LVM if you select
88 `ext4` or `xfs` as a file system, and offers additional options to
89 restrict LVM space (see <<advanced_lvm_options,below>>)
91 If you have more than one disk, you can also use ZFS as a file system.
92 ZFS supports several software RAID levels, which is particularly useful
93 if you do not have a hardware RAID controller. The `Options` button
94 lets you choose the ZFS RAID level and select which disks will be used.
96 image::images/installer/pmg-select-location.png[]
98 The next page asks for basic configuration options like your
99 location, timezone, and keyboard layout. The location is used to
100 select a nearby download server, in order to increase the speed of updates.
101 The installer is usually able to auto-detect these settings, so you only need to
102 change them in rare situations when auto-detection fails, or when you want to
103 use a keyboard layout not commonly used in your country.
105 image::images/installer/pmg-set-password.png[]
107 You then need to specify an email address and the superuser (root)
108 password. The password must have at least 5 characters, but we highly
109 recommend to use stronger passwords - here are some guidelines:
111 - Use a minimum password length of 12 to 14 characters.
113 - Include lowercase and uppercase alphabetic characters, numbers and symbols.
115 - Avoid character repetition, keyboard patterns, dictionary words, letter or
116 number sequences, usernames, relative or pet names, romantic links (current
117 or past) and biographical information (e.g., ID numbers, ancestors' names or
120 It is sometimes necessary to send notification to the system administrator, for
123 - Information about available package updates.
125 - Error messages from periodic cron jobs.
127 All those notification mails will be sent to the specified email address.
129 image::images/installer/pmg-setup-network.png[]
131 The next step is the network configuration. Please note that you can use either
132 IPv4 or IPv6 here, but not both. If you want to configure a dual stack node,
133 you can easily do that after the installation.
135 image::images/installer/pmg-summary.png[]
137 When you press `Next`, you will see an overview of your entered configuration.
138 Please re-check every setting, you can still use the `Previous` button to go
139 back and edit any settings.
141 After clicking `Install`, the installer will begin to format and copy packages
142 to the target disk(s).
144 image::images/installer/pmg-installation.png[]
146 Copying the packages usually takes several minutes. When this is
147 finished, you can reboot the server.
149 Further configuration is done via the {pmg} web interface:
151 [thumbnail="pmg-gui-login-window.png"]
153 . Point your browser to the IP address given during the installation
154 (https://youripaddress:8006).
156 . Log in and upload your subscription key.
158 NOTE: The default login is "root", and the password is the one chosen during the
161 . Check the IP configuration and hostname.
163 . Check the timezone.
165 . Check your xref:firewall_settings[Firewall settings].
167 . Configure {pmg} to forward the incoming SMTP traffic to your mail
168 server ('Configuration/Mail Proxy/Default Relay') - 'Default
169 Relay' is your email server.
171 . Configure your email server to send all outgoing messages through
172 your {pmg} ('Smart Host', port 26 by default).
174 For detailed deployment scenarios see chapter
175 xref:chapter_deployment[Planning for Deployment].
177 After the installation, you have to route all your incoming and
178 outgoing email traffic to {pmg}. For incoming traffic, you
179 have to configure your firewall and/or DNS settings. For outgoing
180 traffic you need to change the existing email server configuration.
183 [[advanced_lvm_options]]
184 Advanced LVM Configuration Options
185 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
187 The installer creates a Volume Group (VG) called `pmg`, and additional
188 Logical Volumes (LVs) called `root` and `swap`. The size of
189 those volumes can be controlled with:
193 Defines the total disk size to be used. This way you can save free
194 space on the disk for further partitioning (i.e. for an additional PV
195 and VG on the same disk that can be used for LVM storage).
199 Defines the size of the `swap` volume. The default is the size of the
200 installed memory. The minimum is 4 GB and the maximum is 8 GB. The resulting
201 value cannot be greater than `hdsize/8`.
205 Defines the amount of free space that should be left in the LVM volume group
206 `pmg`. With more than 128GB storage available, the default is 16GB, otherwise
207 `hdsize/8` will be used.
209 NOTE: LVM requires free space in the VG for snapshot creation (not
210 required for lvmthin snapshots).
216 ZFS uses a lot of memory, so it is best to add additional RAM if you
217 want to use ZFS. A good calculation is 4GB plus 1GB RAM for each TB
220 ZFS also provides the ability to use a fast SSD drive as write cache. The
221 write cache is called the ZFS Intent Log (ZIL). You can add that after
222 the installation using the following command:
224 zpool add <pool-name> log </dev/path_to_fast_ssd>
227 [[pmg_install_on_debian]]
228 Install {pmg} on Debian
229 -----------------------
231 {pmg} ships as a set of Debian packages, so you can install it
232 on top of a normal Debian installation. After configuring the
233 xref:pmg_package_repositories[package repositories], you need to run:
238 apt install proxmox-mailgateway
241 Installing on top of an existing Debian installation seems easy, but
242 it assumes that you have correctly installed the base system, and you
243 know how you want to configure and use the local storage. Network
244 configuration is also completely up to you.
246 NOTE: In general, this is not trivial, especially when you use LVM or
250 [[pmg_install_on_debian_container]]
251 Install {pmg} as a Linux Container Appliance
252 --------------------------------------------
254 {pmg} can also run inside a Debian-based LXC
255 instance. In order to keep the set of installed software, and thus the
256 necessary updates minimal, you can use the `proxmox-mailgateway-container`
257 meta-package. This does not depend on any Linux kernel, firmware, or components
258 used for booting from bare-metal, like grub2.
260 A ready-to-use appliance template is available through the `mail` section of the
261 https://www.proxmox.com/proxmox-ve[Proxmox VE] appliance manager, so if you
262 already use Proxmox VE, you can set up a {pmg} instance in minutes.
264 NOTE: It's recommended to use a static network configuration. If DHCP must be
265 used, ensure that the container always leases the same IP, for example, by
266 reserving one with the container's network MAC address.
268 Additionally, you can install this on top of a container-based Debian
269 installation. After configuring the
270 xref:pmg_package_repositories[package repositories], you need to run:
275 apt install proxmox-mailgateway-container
278 [[pmg_package_repositories]]
282 All {debian} based systems use
283 https://en.wikipedia.org/wiki/Advanced_Packaging_Tool[APT] as a package
284 management tool. The list of repositories is defined in
285 `/etc/apt/sources.list` and `.list` files found inside
286 `/etc/apt/sources.d/`. Updates can be installed directly using
287 `apt`, or via the GUI.
289 Apt `sources.list` files list one package repository per line, with
290 the most preferred source listed first. Empty lines are ignored, and a
291 `#` character anywhere on a line marks the remainder of that line as a
292 comment. The information available from the configured sources is
293 acquired by `apt update`.
295 .File `/etc/apt/sources.list`
297 deb http://ftp.debian.org/debian buster main contrib
299 deb http://ftp.debian.org/debian buster-updates main contrib
302 deb http://security.debian.org/debian-security buster/updates main contrib
304 // FIXME for 7.0: change security update suite to bullseye-security
306 In addition, {pmg} provides three different package repositories.
309 {pmg} Enterprise Repository
310 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
312 This is the default, stable and recommended repository, available for
313 all {pmg} subscription users. It contains the most stable packages,
314 and is suitable for production use. The `pmg-enterprise` repository is
317 .File `/etc/apt/sources.list.d/pmg-enterprise.list`
319 deb https://enterprise.proxmox.com/debian/pmg buster pmg-enterprise
322 As soon as updates are available, the `root@pam` user is notified via
323 email about the newly available packages. From the GUI, the change-log of
324 each package can be viewed (if available), showing all details of the
325 update. Thus, you will never miss important security fixes.
327 Please note that you need a valid subscription key to access this
328 repository. We offer different support levels, which you can find further
329 details about at {pricing-url}.
331 NOTE: You can disable this repository by commenting out the above line
332 using a `#` (at the start of the line). This prevents error messages,
333 if you do not have a subscription key. Please configure the
334 `pmg-no-subscription` repository in this case.
337 {pmg} No-Subscription Repository
338 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
340 As the name suggests, you do not need a subscription key to access
341 this repository. It can be used for testing and non-production
342 use. It's not recommended to use this on production servers, as these
343 packages are not always heavily tested and validated.
345 We recommend configuring this repository in `/etc/apt/sources.list`.
347 .File `/etc/apt/sources.list`
349 deb http://ftp.debian.org/debian buster main contrib
351 # PMG pmg-no-subscription repository provided by proxmox.com,
352 # NOT recommended for production use
353 deb http://download.proxmox.com/debian/pmg buster pmg-no-subscription
356 deb http://security.debian.org/debian-security buster/updates main contrib
360 {pmg} Test Repository
361 ~~~~~~~~~~~~~~~~~~~~~
363 Finally, there is a repository called `pmgtest`. This contains the
364 latest packages, and is heavily used by developers to test new
365 features. As with before, you can configure this using
366 `/etc/apt/sources.list` by adding the following line:
368 .sources.list entry for `pmgtest`
370 deb http://download.proxmox.com/debian/pmg buster pmgtest
373 WARNING: the `pmgtest` repository should only be used
374 for testing new features or bug fixes.
380 We use GnuPG to sign the `Release` files inside these repositories,
381 and APT uses these signatures to verify that all packages are from a
384 The key used for verification is already installed, if you install from
385 our installation CD. If you install via another means, you can manually
386 download the key with:
388 # wget http://download.proxmox.com/debian/proxmox-ve-release-6.x.gpg -O /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
390 Please verify the checksum afterwards:
393 # sha512sum /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
394 acca6f416917e8e11490a08a1e2842d500b3a5d9f322c6319db0927b2901c3eae23cfb5cd5df6facf2b57399d3cfa52ad7769ebdd75d9b204549ca147da52626 /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
400 # md5sum /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
401 f3f6c5a3a67baf38ad178e5ff1ee270c /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
405 Other Repository Sources
406 ~~~~~~~~~~~~~~~~~~~~~~~~
408 Certain software cannot be made available in the `main` and `contrib`
409 areas of the {debian} archives, since it does not adhere to the Debian
410 Free Software Guidelines (DFSG). These are distributed in the
411 {debian_nonfree_archive_area}. For {pmg} two packages from the `non-free` area
412 are needed in order to support the RAR archive format:
414 * `p7zip-rar` for matching xref:pmg_mailfilter_what[Archive Objects] in the
415 xref:chapter_mailfilter[Rule system]
417 * `libclamunrar` for detecting viruses in RAR archives.
419 .Additional sources.list entry for `non-free`
421 deb http://deb.debian.org/debian/ buster non-free
422 deb http://security.debian.org/debian-security buster/updates non-free
423 deb http://deb.debian.org/debian/ buster-updates non-free
426 Following this, you can install the required packages with:
430 apt install libclamunrar p7zip-rar