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 you a few questions, then partitions the local
9 disk(s), installs all required packages, and configures the system
10 including a basic network setup. You can get a fully functional system
11 within a few 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 ext3, 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 (e.g. Boot from USB) the {pmg} menu will be
46 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. It opens a shell console at several
57 installation steps, so that you can debug things if something goes
58 wrong. You can press `CTRL-D` to exit those debug consoles and continue
59 installation. This option is mostly for developers and not meant for
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 First step ist to read our EULA (End User License Agreement). After
80 that you get prompted to select the target hard disk(s).
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 `ext3`,
88 `ext4` or `xfs` as file system, and offers additional option to
89 restrict LVM space (see <<advanced_lvm_options,below>>)
91 If you have more than one disk, you can also use ZFS as file system.
92 ZFS supports several software RAID levels, so this is specially useful
93 if you do not have a hardware RAID controller. The `Options` button
94 lets you select the ZFS RAID level, and you can choose disks there.
96 image::images/installer/pmg-select-location.png[]
98 The next page asks for basic configuration options like your
99 location, the timezone and keyboard layout. The location is used to
100 select a download server near you to speed up updates. The installer is
101 usually able to auto-detect those settings, so you only need to change
102 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 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 pressing `Install`, the installer starts to format disks, and copies
142 packages to the target disk(s).
144 image::images/installer/pmg-installation.png[]
146 Copying the packages usually takes a few minutes. Please wait until that is
147 finished, and reboot the server.
149 Further configuration is done via the Proxmox web interface.
151 [thumbnail="pmg-gui-login-window.png"]
153 Just point your browser to the IP address given during installation
154 (https://youripaddress:8006).
156 . Login and upload subscription key.
158 NOTE: Default login is "root" and the password is chosen during the
161 . Check the IP configuration and hostname.
163 . Check and save 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 e-mail server.
171 . Configure your e-mail 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 e-mail traffic to the {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 e-mail 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, minimum 4 GB and maximum 8 GB. The resulting value cannot
201 be greater than `hdsize/8`.
205 Defines the amount of free space left in LVM volume group `pmg`.
206 With more than 128GB storage available the default is 16GB, else `hdsize/8`
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 feature 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 looks 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 Linux Container Appliance
252 ------------------------------------------
254 The full functionality of {pmg} can also run on top of 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. It 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
261 https://www.proxmox.com/proxmox-ve[Proxmox VE] appliance manager in the `mail`
262 section, so if you already use Proxmox VE you can setup a {pmg} instance in a
265 NOTE: It's recommended to use a static network configuration. If DHCP should be
266 used ensure that the container always leases the same IP, for example, by
267 reserving one with the containers network MAC address.
269 Additionally you can also install this on top of a container based Debian
270 installation. After configuring the
271 xref:pmg_package_repositories[Package repositories], you need to run:
276 apt install proxmox-mailgateway-container
279 [[pmg_package_repositories]]
283 All {debian} based systems use
284 https://en.wikipedia.org/wiki/Advanced_Packaging_Tool[APT] as package
285 management tool. The list of repositories is defined in
286 `/etc/apt/sources.list` and `.list` files found inside
287 `/etc/apt/sources.d/`. Updates can be installed directly using
288 `apt`, or via the GUI.
290 Apt `sources.list` files list one package repository per line, with
291 the most preferred source listed first. Empty lines are ignored, and a
292 `#` character anywhere on a line marks the remainder of that line as a
293 comment. The information available from the configured sources is
294 acquired by `apt update`.
296 .File `/etc/apt/sources.list`
298 deb http://ftp.debian.org/debian buster main contrib
300 deb http://ftp.debian.org/debian buster-updates main contrib
303 deb http://security.debian.org/debian-security buster/updates main contrib
305 // FIXME for 7.0: change security update suite to bullseye-security
307 In addition, {pmg} provides three different package repositories.
310 {pmg} Enterprise Repository
311 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
313 This is the default, stable and recommended repository, available for
314 all {pmg} subscription users. It contains the most stable packages,
315 and is suitable for production use. The `pmg-enterprise` repository is
318 .File `/etc/apt/sources.list.d/pmg-enterprise.list`
320 deb https://enterprise.proxmox.com/debian/pmg buster pmg-enterprise
323 As soon as updates are available, the `root@pam` user is notified via
324 email about the available new packages. On the GUI, the change-log of
325 each package can be viewed (if available), showing all details of the
326 update. So you will never miss important security fixes.
328 Please note that and you need a valid subscription key to access this
329 repository. We offer different support levels, and you can find further
330 details at {pricing-url}.
332 NOTE: You can disable this repository by commenting out the above line
333 using a `#` (at the start of the line). This prevents error messages
334 if you do not have a subscription key. Please configure the
335 `pmg-no-subscription` repository in that case.
338 {pmg} No-Subscription Repository
339 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
341 As the name suggests, you do not need a subscription key to access
342 this repository. It can be used for testing and non-production
343 use. Its not recommended to run on production servers, as these
344 packages are not always heavily tested and validated.
346 We recommend to configure this repository in `/etc/apt/sources.list`.
348 .File `/etc/apt/sources.list`
350 deb http://ftp.debian.org/debian buster main contrib
352 # PMG pmg-no-subscription repository provided by proxmox.com,
353 # NOT recommended for production use
354 deb http://download.proxmox.com/debian/pmg buster pmg-no-subscription
357 deb http://security.debian.org/debian-security buster/updates main contrib
361 {pmg} Test Repository
362 ~~~~~~~~~~~~~~~~~~~~~
364 Finally, there is a repository called `pmgtest`. This one contains the
365 latest packages and is heavily used by developers to test new
366 features. As usual, you can configure this using
367 `/etc/apt/sources.list` by adding the following line:
369 .sources.list entry for `pmgtest`
371 deb http://download.proxmox.com/debian/pmg buster pmgtest
374 WARNING: the `pmgtest` repository should only be used
375 for testing new features or bug fixes.
381 We use GnuPG to sign the `Release` files inside those repositories,
382 and APT uses that signatures to verify that all packages are from a
385 The key used for verification is already installed if you install from
386 our installation CD. If you install by other means, you can manually
387 download the key with:
389 # wget http://download.proxmox.com/debian/proxmox-ve-release-6.x.gpg -O /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
391 Please verify the checksum afterwards:
394 # sha512sum /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
395 acca6f416917e8e11490a08a1e2842d500b3a5d9f322c6319db0927b2901c3eae23cfb5cd5df6facf2b57399d3cfa52ad7769ebdd75d9b204549ca147da52626 /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
401 # md5sum /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
402 f3f6c5a3a67baf38ad178e5ff1ee270c /etc/apt/trusted.gpg.d/proxmox-ve-release-6.x.gpg
406 Other Repository Sources
407 ~~~~~~~~~~~~~~~~~~~~~~~~
409 Certain software cannot be made available in the `main` and `contrib`
410 areas of the {debian} archives, since it does not adhere to the Debian
411 Free Software Guidelines (DFSG). These are distributed in the
412 {debian_nonfree_archive_area}. For {pmg} two packages from the `non-free` area
413 are needed in order to support the RAR archive format:
415 * `p7zip-rar` for matching xref:pmg_mailfilter_what[Archive Objects] in the
416 xref:chapter_mailfilter[Rule system]
418 * `libclamunrar` for detecting viruses in RAR archives.
420 .Additional sources.list entry for `non-free`
422 deb http://deb.debian.org/debian/ buster non-free
423 deb http://security.debian.org/debian-security buster/updates non-free
424 deb http://deb.debian.org/debian/ buster-updates non-free
427 Then you can install the required packages with:
431 apt install libclamunrar p7zip-rar