]>
Commit | Line | Data |
---|---|---|
e62ceaf0 DM |
1 | [[chapter_pmgconfig]] |
2 | ifdef::manvolnum[] | |
3 | pmgconfig(1) | |
4 | ============ | |
5 | :pmg-toplevel: | |
6 | ||
7 | NAME | |
8 | ---- | |
9 | ||
10 | pmgconfig - Proxmox Mail Gateway Configuration Management Toolkit | |
11 | ||
12 | ||
13 | SYNOPSIS | |
14 | -------- | |
15 | ||
16 | include::pmgconfig.1-synopsis.adoc[] | |
17 | ||
18 | ||
19 | DESCRIPTION | |
20 | ----------- | |
21 | endif::manvolnum[] | |
22 | ifndef::manvolnum[] | |
66e9c719 DM |
23 | Configuration Management |
24 | ======================== | |
e62ceaf0 DM |
25 | :pmg-toplevel: |
26 | endif::manvolnum[] | |
27 | ||
685576c2 DM |
28 | {pmg} is usually configured using the web-based Graphical User |
29 | Interface (GUI), but it is also possible to directly edit the | |
eb269701 | 30 | configuration files, using the REST API over 'https' |
66e9c719 | 31 | or the command line tool `pmgsh`. |
685576c2 | 32 | |
66e9c719 | 33 | The command line tool `pmgconfig` is used to simplify some common |
eb269701 | 34 | configuration tasks, such as generating certificates and rewriting |
685576c2 DM |
35 | service configuration files. |
36 | ||
66e9c719 | 37 | NOTE: We use a Postgres database to store mail filter rules and |
eb269701 | 38 | statistical data. See chapter xref:chapter_pmgdb[Database Management] |
66e9c719 DM |
39 | for more information. |
40 | ||
41 | ||
42 | Configuration files overview | |
43 | ---------------------------- | |
44 | ||
45 | `/etc/network/interfaces`:: | |
46 | ||
3f18659b | 47 | Network setup. We never modify this file directly. Instead, we write |
eb269701 DW |
48 | changes to `/etc/network/interfaces.new`. When you reboot, {pmg} renames |
49 | the file to `/etc/network/interfaces`, thus applying the changes. | |
66e9c719 | 50 | |
9bfe27f3 DM |
51 | `/etc/resolv.conf`:: |
52 | ||
fa483193 SI |
53 | DNS search domain and nameserver setup. {pmg} uses the search domain setting |
54 | to create the FQDN and domain name used in the postfix configuration. | |
9bfe27f3 DM |
55 | |
56 | `/etc/hostname`:: | |
57 | ||
eb269701 | 58 | The system's hostname. {pmg} uses the hostname to create the FQDN used |
fa483193 | 59 | in the postfix configuration. |
9bfe27f3 DM |
60 | |
61 | `/etc/hosts`:: | |
62 | ||
63 | Static table lookup for hostnames. | |
64 | ||
66e9c719 DM |
65 | `/etc/pmg/pmg.conf`:: |
66 | ||
eb269701 DW |
67 | Stores common administration options, such as the spam and mail proxy |
68 | configuration. | |
66e9c719 DM |
69 | |
70 | `/etc/pmg/cluster.conf`:: | |
71 | ||
72 | The cluster setup. | |
73 | ||
74 | `/etc/pmg/domains`:: | |
75 | ||
76 | The list of relay domains. | |
77 | ||
5053eecc SI |
78 | `/etc/pmg/dkim/domains`:: |
79 | ||
80 | The list of domains for outbound DKIM signing. | |
81 | ||
66e9c719 DM |
82 | `/etc/pmg/fetchmailrc`:: |
83 | ||
84 | Fetchmail configuration (POP3 and IMAP setup). | |
85 | ||
86 | `/etc/pmg/ldap.conf`:: | |
87 | ||
88 | LDAP configuration. | |
89 | ||
90 | `/etc/pmg/mynetworks`:: | |
91 | ||
92 | List of local (trusted) networks. | |
93 | ||
94 | `/etc/pmg/subscription`:: | |
95 | ||
96 | Stores your subscription key and status. | |
97 | ||
37b2b051 SI |
98 | `/etc/pmg/tls_policy`:: |
99 | ||
100 | TLS policy for outbound connections. | |
101 | ||
66e9c719 DM |
102 | `/etc/pmg/transports`:: |
103 | ||
104 | Message delivery transport setup. | |
105 | ||
106 | `/etc/pmg/user.conf`:: | |
107 | ||
108 | GUI user configuration. | |
109 | ||
797db11d DM |
110 | `/etc/mail/spamassassin/custom.cf`:: |
111 | ||
112 | Custom {spamassassin} setup. | |
113 | ||
8b4756e5 SI |
114 | `/etc/mail/spamassassin/pmg-scores.cf`:: |
115 | ||
116 | Custom {spamassassin} rule scores. | |
66e9c719 DM |
117 | |
118 | Keys and Certificates | |
119 | --------------------- | |
120 | ||
121 | `/etc/pmg/pmg-api.pem`:: | |
122 | ||
eb269701 | 123 | Key and certificate (combined) used by the HTTPS server (API). |
66e9c719 DM |
124 | |
125 | `/etc/pmg/pmg-authkey.key`:: | |
126 | ||
eb269701 | 127 | Private key used to generate authentication tickets. |
66e9c719 DM |
128 | |
129 | `/etc/pmg/pmg-authkey.pub`:: | |
130 | ||
eb269701 | 131 | Public key used to verify authentication tickets. |
66e9c719 DM |
132 | |
133 | `/etc/pmg/pmg-csrf.key`:: | |
134 | ||
135 | Internally used to generate CSRF tokens. | |
136 | ||
137 | `/etc/pmg/pmg-tls.pem`:: | |
138 | ||
139 | Key and certificate (combined) to encrypt mail traffic (TLS). | |
140 | ||
5053eecc SI |
141 | `/etc/pmg/dkim/<selector>.private`:: |
142 | ||
143 | Key for DKIM signing mails with selector '<selector>'. | |
144 | ||
66e9c719 | 145 | |
69a428d9 | 146 | [[pmgconfig_template_engine]] |
66e9c719 DM |
147 | Service Configuration Templates |
148 | ------------------------------- | |
149 | ||
eb269701 | 150 | {pmg} uses various services to implement mail filtering, for example, |
9c85cc80 | 151 | the {postfix} Mail Transport Agent (MTA), the {clamav} antivirus |
eb269701 DW |
152 | engine, and the Apache {spamassassin} project. These services use |
153 | separate configuration files, so we need to rewrite those files when the | |
9c85cc80 DM |
154 | configuration is changed. |
155 | ||
eb269701 | 156 | We use a template-based approach to generate these files. The {tts} is |
9c85cc80 DM |
157 | a well known, fast and flexible template processing system. You can |
158 | find the default templates in `/var/lib/pmg/templates/`. Please do not | |
eb269701 | 159 | modify these directly, otherwise your modifications will be lost on the |
9dd45bd7 SI |
160 | next update. Instead, copy the template you wish to change to |
161 | `/etc/pmg/templates/`, then apply your changes there. | |
9c85cc80 | 162 | |
eb269701 | 163 | Templates can access any configuration settings, and you can use the |
9c85cc80 DM |
164 | `pmgconfig dump` command to get a list of all variable names: |
165 | ||
166 | ---- | |
167 | # pmgconfig dump | |
168 | ... | |
169 | dns.domain = yourdomain.tld | |
170 | dns.hostname = pmg | |
171 | ipconfig.int_ip = 192.168.2.127 | |
172 | pmg.admin.advfilter = 1 | |
173 | ... | |
174 | ---- | |
175 | ||
eb269701 DW |
176 | The same tool is used to force the regeneration of all template-based |
177 | configuration files. You need to run the following after modifying a template, | |
178 | or when you directly edit configuration files: | |
9c85cc80 DM |
179 | |
180 | ---- | |
181 | # pmgconfig sync --restart 1 | |
182 | ---- | |
183 | ||
9dd45bd7 | 184 | The above command also restarts services if the underlying configuration |
9c85cc80 DM |
185 | files are changed. Please note that this is automatically done when |
186 | you change the configuration using the GUI or API. | |
187 | ||
188 | NOTE: Modified templates from `/etc/pmg/templates/` are automatically | |
189 | synced from the master node to all cluster members. | |
66e9c719 | 190 | |
7e7126d6 ML |
191 | [[pmgconfig_whitelist_overview]] |
192 | White- and Blacklists | |
193 | --------------------- | |
194 | ||
eb269701 DW |
195 | {pmg} has multiple white- and blacklists. It differentiates between the |
196 | xref:pmgconfig_mailproxy_options[SMTP Whitelist], the rule-based whitelist | |
7e7126d6 | 197 | and the user whitelist. |
eb269701 | 198 | In addition to the whitelists, there are two separate blacklists: the rule-based |
7e7126d6 ML |
199 | blacklist and the user blacklist. |
200 | ||
201 | SMTP Whitelist | |
202 | ~~~~~~~~~~~~~~ | |
203 | ||
204 | The xref:pmgconfig_mailproxy_options[SMTP Whitelist] is responsible for disabling | |
eb269701 | 205 | greylisting, as well as SPF and DNSBL checks. These are done during the SMTP |
7e7126d6 ML |
206 | dialogue. |
207 | ||
208 | Rule-based White-/Blacklist | |
209 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
210 | ||
211 | The xref:chapter_mailfilter[rule-based white- and blacklists] are predefined | |
eb269701 DW |
212 | rules. They work by checking the attached 'Who' objects, containing, for |
213 | example, a domain or a mail address for a match. If it matches, the assigned | |
214 | action is used, which by default is 'Accept' for the whitelist rule and 'Block' | |
215 | for the blacklist rule. In the default setup, the blacklist rule has priority | |
216 | over the whitelist rule and spam checks. | |
7e7126d6 ML |
217 | |
218 | User White-/Blacklist | |
219 | ~~~~~~~~~~~~~~~~~~~~~ | |
220 | ||
221 | The user white- and blacklist are user specific. Every user can add mail addresses | |
222 | to their white- and blacklist. When a user adds a mail address to the whitelist, | |
223 | the result of the spam analysis will be discarded for that recipient. This can | |
eb269701 DW |
224 | help in the mail being accepted, but what happens next still depends on the |
225 | other rules. In the default setup, this results in the mail being accepted for | |
7e7126d6 ML |
226 | this recipient. |
227 | ||
eb269701 DW |
228 | For mail addresses on a user's blacklist, the spam score will be increased by |
229 | 100. What happens when a high spam score is encountered still depends on the | |
230 | rule system. In the default setup, it will be recognized as spam and quarantined | |
7e7126d6 | 231 | (spam score of 3 or higher). |
66e9c719 | 232 | |
4a08dffe | 233 | [[pmgconfig_systemconfig]] |
685576c2 DM |
234 | System Configuration |
235 | -------------------- | |
236 | ||
237 | Network and Time | |
238 | ~~~~~~~~~~~~~~~~ | |
239 | ||
240 | ifndef::manvolnum[] | |
a695a527 | 241 | [thumbnail="pmg-gui-network-config.png", big=1] |
685576c2 DM |
242 | endif::manvolnum[] |
243 | ||
eb269701 DW |
244 | As network and time are configured in the installer, these generally do not |
245 | need to be configured again in the GUI. | |
45de5bf5 DM |
246 | |
247 | The default setup uses a single Ethernet adapter and static IP | |
248 | assignment. The configuration is stored at '/etc/network/interfaces', | |
eb269701 | 249 | and the actual network setup is done the standard Debian way, using the |
45de5bf5 DM |
250 | package 'ifupdown'. |
251 | ||
252 | .Example network setup '/etc/network/interfaces' | |
253 | ---- | |
254 | source /etc/network/interfaces.d/* | |
255 | ||
256 | auto lo | |
257 | iface lo inet loopback | |
258 | ||
259 | auto ens18 | |
260 | iface ens18 inet static | |
261 | address 192.168.2.127 | |
262 | netmask 255.255.240.0 | |
263 | gateway 192.168.2.1 | |
264 | ---- | |
265 | ||
266 | .DNS recommendations | |
267 | ||
268 | Many tests to detect SPAM mails use DNS queries, so it is important to | |
3f18659b | 269 | have a fast and reliable DNS server. We also query some publicly |
45de5bf5 DM |
270 | available DNS Blacklists. Most of them apply rate limits for clients, |
271 | so they simply will not work if you use a public DNS server (because | |
272 | they are usually blocked). We recommend to use your own DNS server, | |
3f18659b | 273 | which needs to be configured in 'recursive' mode. |
685576c2 DM |
274 | |
275 | ||
276 | Options | |
277 | ~~~~~~~ | |
278 | ||
279 | ifndef::manvolnum[] | |
a695a527 | 280 | [thumbnail="pmg-gui-system-options.png", big=1] |
685576c2 DM |
281 | endif::manvolnum[] |
282 | ||
e09057ab | 283 | |
eb269701 | 284 | These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`, |
e09057ab DM |
285 | using the following configuration keys: |
286 | ||
685576c2 DM |
287 | include::pmg.admin-conf-opts.adoc[] |
288 | ||
c331641e | 289 | |
8c889e95 TL |
290 | include::pmg-ssl-certificate.adoc[] |
291 | ||
c331641e DM |
292 | Mail Proxy Configuration |
293 | ------------------------ | |
294 | ||
4a08dffe | 295 | [[pmgconfig_mailproxy_relaying]] |
c331641e DM |
296 | Relaying |
297 | ~~~~~~~~ | |
298 | ||
c331641e | 299 | ifndef::manvolnum[] |
a695a527 | 300 | [thumbnail="pmg-gui-mailproxy-relaying.png", big=1] |
c331641e DM |
301 | endif::manvolnum[] |
302 | ||
eb269701 | 303 | These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`, |
e09057ab DM |
304 | using the following configuration keys: |
305 | ||
306 | include::pmg.mail-relaying-conf-opts.adoc[] | |
c331641e | 307 | |
4a08dffe | 308 | [[pmgconfig_mailproxy_relay_domains]] |
c331641e DM |
309 | Relay Domains |
310 | ~~~~~~~~~~~~~ | |
311 | ||
c331641e | 312 | ifndef::manvolnum[] |
a695a527 | 313 | [thumbnail="pmg-gui-mailproxy-relaydomains.png", big=1] |
c331641e DM |
314 | endif::manvolnum[] |
315 | ||
eb269701 | 316 | A list of relayed mail domains, that is, what destination domains this |
6822b369 DM |
317 | system will relay mail to. The system will reject incoming mails to |
318 | other domains. | |
c331641e | 319 | |
d9c56b22 | 320 | |
4a08dffe | 321 | [[pmgconfig_mailproxy_ports]] |
c331641e DM |
322 | Ports |
323 | ~~~~~ | |
324 | ||
c331641e | 325 | ifndef::manvolnum[] |
a695a527 | 326 | [thumbnail="pmg-gui-mailproxy-ports.png", big=1] |
c331641e DM |
327 | endif::manvolnum[] |
328 | ||
eb269701 | 329 | These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`, |
d9c56b22 DM |
330 | using the following configuration keys: |
331 | ||
332 | include::pmg.mail-ports-conf-opts.adoc[] | |
333 | ||
c331641e | 334 | |
4a08dffe | 335 | [[pmgconfig_mailproxy_options]] |
c331641e DM |
336 | Options |
337 | ~~~~~~~ | |
338 | ||
c331641e | 339 | ifndef::manvolnum[] |
a695a527 | 340 | [thumbnail="pmg-gui-mailproxy-options.png", big=1] |
c331641e DM |
341 | endif::manvolnum[] |
342 | ||
eb269701 | 343 | These settings are saved to the 'mail' subsection in `/etc/pmg/pmg.conf`, |
e3d778e0 DM |
344 | using the following configuration keys: |
345 | ||
346 | include::pmg.mail-options-conf-opts.adoc[] | |
c331641e DM |
347 | |
348 | ||
89028579 SI |
349 | [[pmgconfig_mailproxy_before_after_queue]] |
350 | Before and After Queue scanning | |
351 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
352 | ||
eb269701 | 353 | Email scanning can happen at two different stages of mail-processing: |
89028579 | 354 | |
eb269701 | 355 | * Before-queue filtering: During the SMTP session, after the complete message |
1824eab9 | 356 | has been received (after the 'DATA' command). |
89028579 | 357 | |
1824eab9 SI |
358 | * After-queue filtering: After initially accepting the mail and putting it on |
359 | a queue for further processing. | |
89028579 | 360 | |
1824eab9 SI |
361 | Before-queue filtering has the advantage that the system can reject a mail (by |
362 | sending a permanent reject code '554'), and leave the task of notifying the | |
eb269701 | 363 | original sender to the other mail server. This is of particular advantage if |
1824eab9 | 364 | the processed mail is a spam message or contains a virus and has a forged |
eb269701 | 365 | sender address. Sending out a notification in this situation leads to so-called |
89028579 | 366 | 'backscatter' mail, which might cause your server to get listed as spamming on |
3f18659b | 367 | RBLs (Real-time Blackhole List). |
89028579 | 368 | |
1824eab9 | 369 | After-queue filtering has the advantage of providing faster delivery of |
eb269701 DW |
370 | mails for the sending servers, since queuing emails is much faster than |
371 | analyzing them for spam and viruses. | |
372 | ||
373 | If a mail is addressed to multiple recipients (for example, when multiple | |
374 | addresses are subscribed to the same mailing list), the situation is more | |
375 | complicated; your mail server can only reject or accept the mail for all | |
376 | recipients, after having received the complete message, while your rule setup | |
377 | might accept the mail for part of the recipients and reject it for others. This | |
378 | can be due to a complicated rule setup, or if your users use the 'User White- | |
379 | and Blacklist' feature. | |
380 | ||
381 | If the resulting action of the rule system is the same for all recipients, {pmg} | |
382 | responds accordingly, if configured for before-queue filtering (sending '554' | |
89028579 | 383 | for a blocked mail and '250' for an accepted or quarantined mail). If some |
3f18659b | 384 | mailboxes accept the mail and some reject it, the system has to accept the mail. |
89028579 SI |
385 | |
386 | Whether {pmg} notifies the sender that delivery failed for some recipients by | |
387 | sending a non-delivery report, depends on the 'ndr_on_block' setting in | |
eb269701 | 388 | '/etc/pmg/pmg.conf'. If enabled, an NDR is sent. Keeping this disabled prevents |
89028579 | 389 | NDRs being sent to the (possibly forged) sender and thus minimizes the chance |
eb269701 | 390 | of getting your IP listed on an RBL. However in certain environments, it can be |
89028579 SI |
391 | unacceptable not to inform the sender about a rejected mail. |
392 | ||
eb269701 | 393 | The setting has the same effect if after-queue filtering is configured, with |
89028579 SI |
394 | the exception that an NDR is always sent out, even if all recipients block the |
395 | mail, since the mail already got accepted before being analyzed. | |
396 | ||
397 | The details of integrating the mail proxy with {postfix} in both setups are | |
398 | explained in {postfix_beforequeue} and {postfix_afterqueue} respectively. | |
399 | ||
89028579 | 400 | |
d41aa039 SI |
401 | [[pmgconfig_mailproxy_greylisting]] |
402 | Greylisting | |
403 | ~~~~~~~~~~~ | |
404 | ||
405 | Greylisting is a technique for preventing unwanted messages from reaching the | |
406 | resource intensive stages of content analysis (virus detection and spam | |
eb269701 DW |
407 | detection). By initially replying with a temporary failure code ('450') to |
408 | each new email, {pmg} tells the sending server that it should queue the | |
409 | mail and retry delivery at a later point. Since certain kinds of spam get | |
410 | sent out by software which has no provisioning for queuing, these mails are | |
d41aa039 SI |
411 | dropped without reaching {pmg} or your mailbox. |
412 | ||
413 | The downside of greylisting is the delay introduced by the initial deferral of | |
414 | the email, which usually amounts to less than 30 minutes. | |
415 | ||
416 | In order to prevent unnecessary delays in delivery from known sources, emails | |
417 | coming from a source for a recipient, which have passed greylisting in the | |
418 | past are directly passed on: For each email the triple '<sender network, | |
419 | sender email, recipient email>' is stored in a list, along with the time when | |
420 | delivery was attempted. If an email fits an already existing triple, the | |
eb269701 | 421 | timestamp for that triple is updated, and the email is accepted for further |
d41aa039 SI |
422 | processing. |
423 | ||
eb269701 | 424 | As long as a sender and recipient communicate frequently, there is no delay |
d41aa039 | 425 | introduced by enabling greylisting. A triple is removed after a longer period |
eb269701 | 426 | of time, if no mail fitting that triple has been seen. The timeouts in {pmg} |
d41aa039 SI |
427 | are: |
428 | ||
429 | * 2 days for the retry of the first delivery | |
430 | ||
eb269701 | 431 | * 36 days for a known triple |
d41aa039 | 432 | |
eb269701 | 433 | Mails with an empty envelope sender are always delayed. |
d41aa039 SI |
434 | |
435 | Some email service providers send out emails for one domain from multiple | |
eb269701 DW |
436 | servers. To prevent delays due to an email coming in from two separate IPs of |
437 | the same provider, the triples store a network ('cidr') instead of a single IP. | |
438 | For certain large providers, the default network size might be too small. You | |
d41aa039 SI |
439 | can configure the netmask applied to an IP for the greylist lookup in |
440 | '/etc/pmg/pmg.conf' or in the GUI with the settings 'greylistmask' for IPv4 | |
441 | and 'greylistmask6' for IPv6 respectively. | |
442 | ||
443 | ||
4a08dffe | 444 | [[pmgconfig_mailproxy_transports]] |
c331641e DM |
445 | Transports |
446 | ~~~~~~~~~~ | |
447 | ||
448 | ifndef::manvolnum[] | |
a695a527 | 449 | [thumbnail="pmg-gui-mailproxy-transports.png", big=1] |
c331641e DM |
450 | endif::manvolnum[] |
451 | ||
3599cb04 | 452 | You can use {pmg} to send emails to different internal email servers. For |
eb269701 | 453 | example, you can send emails addressed to domain.com to your first email server |
3599cb04 | 454 | and emails addressed to subdomain.domain.com to a second one. |
b335e06b | 455 | |
31259590 | 456 | You can add the IP addresses, hostname, transport protocol (smtp/lmtp), |
3599cb04 TL |
457 | transport ports and mail domains (or just single email addresses) of your |
458 | additional email servers. When transport protocol is set to `lmtp`, the option | |
eb269701 | 459 | 'Use MX' is useless and will automatically be set to 'No'. |
c331641e DM |
460 | |
461 | ||
4a08dffe | 462 | [[pmgconfig_mailproxy_networks]] |
c331641e DM |
463 | Networks |
464 | ~~~~~~~~ | |
465 | ||
466 | ifndef::manvolnum[] | |
a695a527 | 467 | [thumbnail="pmg-gui-mailproxy-networks.png", big=1] |
c331641e DM |
468 | endif::manvolnum[] |
469 | ||
3599cb04 TL |
470 | You can add additional internal (trusted) IP networks or hosts. All hosts in |
471 | this list are allowed to relay. | |
20e879ad | 472 | |
eb269701 DW |
473 | NOTE: Hosts in the same subnet as {pmg} can relay by default and don't need to |
474 | be added to this list. | |
c331641e DM |
475 | |
476 | ||
4a08dffe | 477 | [[pmgconfig_mailproxy_tls]] |
c331641e DM |
478 | TLS |
479 | ~~~ | |
480 | ||
481 | ifndef::manvolnum[] | |
a695a527 | 482 | [thumbnail="pmg-gui-mailproxy-tls.png", big=1] |
c331641e DM |
483 | endif::manvolnum[] |
484 | ||
3599cb04 TL |
485 | Transport Layer Security (TLS) provides certificate-based authentication and |
486 | encrypted sessions. An encrypted session protects the information that is | |
487 | transmitted with SMTP mail. When you activate TLS, {pmg} automatically | |
488 | generates a new self signed certificate for you (`/etc/pmg/pmg-tls.pem`). | |
20e879ad | 489 | |
37b2b051 | 490 | {pmg} uses opportunistic TLS encryption by default. The SMTP transaction is |
20e879ad | 491 | encrypted if the 'STARTTLS' ESMTP feature is supported by the remote |
eb269701 | 492 | server. Otherwise, messages are sent unencrypted. |
91d501f6 SI |
493 | |
494 | You can set a different TLS policy per destination. A destination is either a | |
eb269701 | 495 | remote domain or a next-hop destination, as specified in `/etc/pmg/transport`. |
3f18659b | 496 | This can be used if you need to prevent email delivery without |
91d501f6 SI |
497 | encryption, or to work around a broken 'STARTTLS' ESMTP implementation. See |
498 | {postfix_tls_readme} for details on the supported policies. | |
20e879ad DM |
499 | |
500 | Enable TLS logging:: | |
501 | ||
eb269701 DW |
502 | To get additional information about SMTP TLS activity, you can enable |
503 | TLS logging. In this case, information about TLS sessions and used | |
3f18659b | 504 | certificates is logged via syslog. |
20e879ad DM |
505 | |
506 | Add TLS received header:: | |
507 | ||
508 | Set this option to include information about the protocol and cipher | |
eb269701 | 509 | used, as well as the client and issuer CommonName into the "Received:" |
20e879ad DM |
510 | message header. |
511 | ||
a649b38f DM |
512 | Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`, |
513 | using the following configuration keys: | |
514 | ||
515 | include::pmg.mail-tls-conf-opts.adoc[] | |
516 | ||
c331641e | 517 | |
20522d96 SI |
518 | [[pmgconfig_mailproxy_dkim]] |
519 | DKIM Signing | |
520 | ~~~~~~~~~~~~ | |
521 | ||
f5fddbff | 522 | ifndef::manvolnum[] |
a695a527 | 523 | [thumbnail="pmg-gui-mailproxy-dkim.png", big=1] |
f5fddbff SI |
524 | endif::manvolnum[] |
525 | ||
20522d96 SI |
526 | DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) is a method to |
527 | cryptographically authenticate a mail as originating from a particular domain. | |
eb269701 | 528 | Before sending the mail, a hash over certain header fields and the body is |
20522d96 SI |
529 | computed, signed with a private key and added in the `DKIM-Signature` header of |
530 | the mail. The 'selector' (a short identifier chosen by you, used to identify | |
531 | which system and private key were used for signing) is also included in the | |
532 | `DKIM-Signature` header. | |
533 | ||
eb269701 | 534 | The verification is done by the receiver. The public key is fetched |
20522d96 SI |
535 | via DNS TXT lookup for `yourselector._domainkey.yourdomain.example` and used |
536 | for verifying the hash. You can publish multiple selectors for your domain, | |
3f18659b | 537 | each used by a system which sends email from your domain, without the need to |
20522d96 SI |
538 | share the private key. |
539 | ||
540 | {pmg} verifies DKIM Signatures for inbound mail in the Spam Filter by default. | |
541 | ||
eb269701 DW |
542 | Additionally, it supports conditionally signing outbound mail, if configured. |
543 | It uses one private key and selector per {pmg} deployment (all nodes in a | |
544 | cluster use the same key). The key has a minimal size of 1024 bits and | |
545 | rsa-sha256 is used as the signing algorithm. | |
20522d96 SI |
546 | |
547 | The headers included in the signature are taken from the list of | |
548 | `Mail::DKIM::Signer`. Additionally `Content-Type` (if present), `From`, `To`, | |
549 | `CC`, `Reply-To` and `Subject` get oversigned. | |
550 | ||
551 | You can either sign all mails received on the internal port using the domain of | |
3f18659b | 552 | the envelope sender address or create a list of domains, for which emails |
20522d96 SI |
553 | should be signed, defaulting to the list of relay domains. |
554 | ||
555 | ||
556 | Enable DKIM Signing:: | |
557 | ||
558 | Controls whether outbound mail should get DKIM signed. | |
559 | ||
560 | Selector:: | |
561 | ||
562 | The selector used for signing the mail. The private key used for signing is | |
3fe91910 | 563 | saved under `/etc/pmg/dkim/yourselector.private`. You can display the DNS TXT |
20522d96 SI |
564 | record which you need to add to all domains signed by {pmg} by clicking on the |
565 | 'View DNS Record' Button. | |
566 | ||
567 | Sign all Outgoing Mail:: | |
568 | ||
569 | Controls whether all outbound mail should get signed or only mails from domains | |
eb269701 DW |
570 | listed in `/etc/pmg/dkim/domains`, if it exists and `/etc/pmg/domains` |
571 | otherwise. | |
20522d96 | 572 | |
eb269701 | 573 | These settings are saved to the 'admin' subsection in `/etc/pmg/pmg.conf`, |
20522d96 SI |
574 | using the following configuration keys: |
575 | ||
576 | include::pmg.admin-dkim-conf-opts.adoc[] | |
577 | ||
578 | ||
c331641e DM |
579 | Whitelist |
580 | ~~~~~~~~~ | |
581 | ||
582 | ifndef::manvolnum[] | |
a695a527 | 583 | [thumbnail="pmg-gui-mailproxy-whitelist.png", big=1] |
c331641e DM |
584 | endif::manvolnum[] |
585 | ||
3f18659b | 586 | All SMTP checks are disabled for those entries (e.g. Greylisting, |
74ec1f38 ML |
587 | SPF, DNSBL, ...) |
588 | ||
eb269701 | 589 | DNSBL checks are done by `postscreen`, which works on IP addresses and networks. |
74ec1f38 | 590 | This means it can only make use of the `IP Address` and `IP Network` entries. |
6822b369 | 591 | |
eb269701 | 592 | NOTE: If you use a backup MX server (for example, your ISP offers this service |
6822b369 | 593 | for you) you should always add those servers here. |
c331641e | 594 | |
74ec1f38 ML |
595 | NOTE: To disable DNSBL checks entirely, remove any `DNSBL Sites` entries in |
596 | xref:pmgconfig_mailproxy_options[Mail Proxy Options]. | |
c331641e | 597 | |
4a08dffe | 598 | [[pmgconfig_spamdetector]] |
c331641e DM |
599 | Spam Detector Configuration |
600 | --------------------------- | |
601 | ||
2d672352 DM |
602 | Options |
603 | ~~~~~~~ | |
604 | ||
74bfe8ba | 605 | ifndef::manvolnum[] |
a695a527 | 606 | [thumbnail="pmg-gui-spam-options.png", big=1] |
74bfe8ba DM |
607 | endif::manvolnum[] |
608 | ||
3371c521 DM |
609 | {pmg} uses a wide variety of local and network tests to identify spam |
610 | signatures. This makes it harder for spammers to identify one aspect | |
611 | which they can craft their messages to work around the spam filter. | |
612 | ||
eb269701 | 613 | Every single email will be analyzed and have a spam score |
3371c521 DM |
614 | assigned. The system attempts to optimize the efficiency of the rules |
615 | that are run in terms of minimizing the number of false positives and | |
616 | false negatives. | |
617 | ||
618 | include::pmg.spam-conf-opts.adoc[] | |
619 | ||
620 | ||
4a08dffe | 621 | [[pmgconfig_spamdetector_quarantine]] |
2d672352 DM |
622 | Quarantine |
623 | ~~~~~~~~~~ | |
3371c521 | 624 | |
74bfe8ba | 625 | ifndef::manvolnum[] |
a695a527 | 626 | [thumbnail="pmg-gui-spamquar-options.png", big=1] |
74bfe8ba DM |
627 | endif::manvolnum[] |
628 | ||
3f18659b OB |
629 | {pmg} analyses all incoming email messages and decides for each |
630 | email if it is ham or spam (or virus). Good emails are delivered to | |
631 | the inbox and spam messages are moved into the spam quarantine. | |
3371c521 DM |
632 | |
633 | The system can be configured to send daily reports to inform users | |
eb269701 | 634 | about personal spam messages received in the last day. The report is |
3371c521 DM |
635 | only sent if there are new messages in the quarantine. |
636 | ||
ee34edb0 | 637 | Some options are only available in the config file `/etc/pmg/pmg.conf`, |
3f18659b | 638 | and not in the web interface. |
ee34edb0 | 639 | |
3371c521 | 640 | include::pmg.spamquar-conf-opts.adoc[] |
c331641e DM |
641 | |
642 | ||
36b169e6 SI |
643 | [[pmgconfig_spamdetector_customscores]] |
644 | Customization of Rulescores | |
645 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
646 | ||
f5fddbff | 647 | ifndef::manvolnum[] |
a695a527 | 648 | [thumbnail="pmg-gui-spam-custom-scores.png", big=1] |
f5fddbff SI |
649 | endif::manvolnum[] |
650 | ||
36b169e6 SI |
651 | While the default scoring of {spamassassin}'s ruleset provides very good |
652 | detection rates, sometimes your particular environment can benefit from | |
653 | slightly adjusting the score of a particular rule. Two examples: | |
654 | ||
655 | * Your system receives spam mails which are scored at 4.9 and you have | |
656 | a rule which puts all mails above 5 in the quarantine. The one thing the | |
657 | spam mails have in common is that they all hit 'URIBL_BLACK'. By increasing | |
658 | the score of this rule by 0.2 points the spam mails would all be quarantined | |
659 | instead of being sent to your users | |
660 | ||
661 | * Your system tags many legitimate mails from a partner organization as spam, | |
662 | because the organization has a policy that each mail has to start with | |
663 | 'Dear madam or sir' (generating 1.9 points through the rule | |
eb269701 | 664 | 'DEAR_SOMETHING'). By setting the score of this rule to 0, you can disable |
36b169e6 SI |
665 | it completely. |
666 | ||
3f18659b | 667 | The system logs all the rules which a particular mail hits. Analyzing the logs can |
36b169e6 SI |
668 | lead to finding such a pattern in your environment. |
669 | ||
670 | You can adjust the score of a rule by creating a new 'Custom Rule Score' entry | |
671 | in the GUI. | |
672 | ||
eb269701 | 673 | NOTE: In general, it is strongly recommended not to make large changes to the |
36b169e6 SI |
674 | default scores. |
675 | ||
676 | ||
4a08dffe | 677 | [[pmgconfig_clamav]] |
c331641e DM |
678 | Virus Detector Configuration |
679 | ---------------------------- | |
680 | ||
4a08dffe | 681 | [[pmgconfig_clamav_options]] |
2d672352 DM |
682 | Options |
683 | ~~~~~~~ | |
684 | ||
e7c18c7c | 685 | ifndef::manvolnum[] |
a695a527 | 686 | [thumbnail="pmg-gui-virus-options.png", big=1] |
e7c18c7c DM |
687 | endif::manvolnum[] |
688 | ||
0bfbbf88 | 689 | All mails are automatically passed to the included virus detector |
3f18659b | 690 | ({clamav}). The default settings are considered safe, so it is usually |
0bfbbf88 DM |
691 | not required to change them. |
692 | ||
693 | {clamav} related settings are saved to subsection 'clamav' in `/etc/pmg/pmg.conf`, | |
694 | using the following configuration keys: | |
695 | ||
696 | include::pmg.clamav-conf-opts.adoc[] | |
697 | ||
e7c18c7c | 698 | ifndef::manvolnum[] |
a695a527 | 699 | [thumbnail="pmg-gui-clamav-database.png", big=1] |
e7c18c7c DM |
700 | endif::manvolnum[] |
701 | ||
3f18659b OB |
702 | Please note that the virus signature database is automatically |
703 | updated. You can see the database status in the GUI, and also | |
eb269701 | 704 | trigger manual updates from there. |
e7c18c7c | 705 | |
0bfbbf88 | 706 | |
4a08dffe | 707 | [[pmgconfig_clamav_quarantine]] |
2d672352 DM |
708 | Quarantine |
709 | ~~~~~~~~~~ | |
0bfbbf88 | 710 | |
e7c18c7c | 711 | ifndef::manvolnum[] |
a695a527 | 712 | [thumbnail="pmg-gui-virusquar-options.png", big=1] |
e7c18c7c DM |
713 | endif::manvolnum[] |
714 | ||
eb269701 DW |
715 | Identified virus mails are automatically moved to the virus |
716 | quarantine. The administrator can view these mails from the GUI, and | |
717 | choose to deliver them, in case of false positives. {pmg} does not notify | |
0bfbbf88 DM |
718 | individual users about received virus mails. |
719 | ||
720 | Virus quarantine related settings are saved to subsection 'virusquar' | |
721 | in `/etc/pmg/pmg.conf`, using the following configuration keys: | |
722 | ||
723 | include::pmg.virusquar-conf-opts.adoc[] | |
c331641e DM |
724 | |
725 | ||
7eff8815 DM |
726 | Custom SpamAssassin configuration |
727 | --------------------------------- | |
728 | ||
833e1edc SI |
729 | This is only for advanced users. {spamassassin}'s rules and their associated |
730 | scores get updated regularly and are trained on a huge corpus, which gets | |
eb269701 | 731 | classified by experts. In most cases, adding a rule for matching a particular |
833e1edc SI |
732 | keyword is the wrong approach, leading to many false positives. Usually bad |
733 | detection rates are better addressed by properly setting up DNS than by adding | |
734 | a custom rule - watch out for matches to 'URIBL_BLOCKED' in the logs or | |
735 | spam-headers - see the {spamassassin_dnsbl}. | |
736 | ||
eb269701 DW |
737 | To add or change the Proxmox {spamassassin} configuration, log in to the |
738 | console via SSH and change to the `/etc/mail/spamassassin/` directory. In this | |
d2f49775 | 739 | directory there are several files (`init.pre`, `local.cf`, ...) - do not change |
69a428d9 SI |
740 | them, as `init.pre`, `v310.pre`, `v320.pre`, `local.cf` will be overwritten by |
741 | the xref:pmgconfig_template_engine[template engine], while the others can | |
742 | get updated by any {spamassassin} package upgrade. | |
833e1edc | 743 | |
3f18659b | 744 | To add your custom configuration, you have to create a new file and name it |
d2f49775 | 745 | `custom.cf` (in this directory), then add your configuration there. Make sure |
3f18659b | 746 | to use the correct {spamassassin} syntax, and test it with: |
7eff8815 DM |
747 | |
748 | ---- | |
749 | # spamassassin -D --lint | |
750 | ---- | |
751 | ||
752 | If you run a cluster, the `custom.cf` file is synchronized from the | |
d2f49775 | 753 | master node to all cluster members automatically. |
7eff8815 | 754 | |
eb269701 | 755 | To adjust the score assigned to a particular rule, you |
36b169e6 SI |
756 | can also use the xref:pmgconfig_spamdetector_customscores[Custom Rule Score] |
757 | settings in the GUI. | |
758 | ||
7eff8815 | 759 | |
ed7970d8 SI |
760 | [[pmgconfig_custom_check]] |
761 | Custom Check Interface | |
762 | ---------------------- | |
763 | ||
3f18659b | 764 | For use-cases which are not handled by the {pmg} Virus Detector and |
ed7970d8 SI |
765 | {spamassassin} configuration, advanced users can create a custom check |
766 | executable which, if enabled will be called before the Virus Detector and before | |
3f18659b | 767 | passing an email through the Rule System. The custom check API is kept as |
ed7970d8 | 768 | simple as possible, while still providing a great deal of control over the |
3f18659b | 769 | treatment of an email. Its input is passed via two CLI arguments: |
ed7970d8 SI |
770 | |
771 | * the 'api-version' (currently `v1`) - for potential future change of the | |
772 | invocation | |
773 | ||
3f18659b | 774 | * the 'queue-file-name' - a filename, which contains the complete email as |
ed7970d8 SI |
775 | rfc822/eml file |
776 | ||
eb269701 | 777 | The expected output needs to be printed to STDOUT and consists of two lines: |
ed7970d8 SI |
778 | |
779 | * the 'api-version' (currently 'v1') - see above | |
780 | ||
781 | * one of the following 3 results: | |
eb269701 | 782 | ** 'OK' - email is OK |
3f18659b OB |
783 | ** 'VIRUS: <virusdescription>' - email is treated as if it contained a virus |
784 | (the virus description is logged and added to the email's headers) | |
ed7970d8 | 785 | ** 'SCORE: <number>' - <number> is added (negative numbers are also possible) |
3f18659b | 786 | to the email's spamscore |
ed7970d8 | 787 | |
eb269701 | 788 | The check is run with a 5 minute timeout - if this is exceeded, the check |
3f18659b | 789 | executable is killed and the email is treated as OK. |
ed7970d8 SI |
790 | |
791 | All output written to STDERR by the check is written with priority 'err' to the | |
792 | journal/mail.log. | |
793 | ||
eb269701 DW |
794 | Below is a simple sample script following the API (and yielding a random result) |
795 | for reference: | |
ed7970d8 SI |
796 | |
797 | ---- | |
798 | #!/bin/sh | |
799 | ||
800 | echo "called with $*" 1>&2 | |
801 | ||
802 | if [ "$#" -ne 2 ]; then | |
803 | echo "usage: $0 APIVERSION QUEUEFILENAME" 1>&2 | |
804 | exit 1 | |
805 | fi | |
806 | ||
807 | apiver="$1" | |
808 | shift | |
809 | ||
810 | if [ "$apiver" != "v1" ]; then | |
811 | echo "wrong APIVERSION: $apiver" 1>&2 | |
812 | exit 2 | |
813 | fi | |
814 | ||
815 | queue_file="$1" | |
816 | ||
817 | echo "v1" | |
818 | ||
819 | choice=$(shuf -i 0-3 -n1) | |
820 | ||
821 | case "$choice" in | |
822 | 0) | |
823 | echo OK | |
824 | ;; | |
825 | 1) | |
826 | echo SCORE: 4 | |
827 | ;; | |
828 | 2) | |
829 | echo VIRUS: Random Virus | |
830 | ;; | |
831 | 3) #timeout-test | |
832 | for i in $(seq 1 7); do | |
833 | echo "custom checking mail: $queue_file - minute $i" 1>&2 | |
834 | sleep 60 | |
835 | done | |
836 | ;; | |
837 | esac | |
838 | ||
839 | exit 0 | |
840 | ---- | |
841 | ||
842 | The custom check needs to be enabled in the admin section of `/etc/pmg/pmg.conf` | |
843 | ||
844 | ---- | |
845 | section: admin | |
846 | custom_check 1 | |
847 | ---- | |
848 | ||
849 | The location of the custom check executable can also be set there with the key | |
850 | `custom_check_path` and defaults to `/usr/local/bin/pmg-custom-check`. | |
851 | ||
852 | ||
c331641e DM |
853 | User Management |
854 | --------------- | |
855 | ||
05336835 DC |
856 | User management in {pmg} consists of three types of users/accounts: |
857 | ||
858 | ||
4a08dffe | 859 | [[pmgconfig_localuser]] |
05336835 DC |
860 | Local Users |
861 | ~~~~~~~~~~~ | |
862 | ||
a695a527 | 863 | [thumbnail="pmg-gui-local-user-config.png", big=1] |
f02d2b90 | 864 | |
4885bff7 TL |
865 | Local users can manage and audit {pmg}. They can login on the management web |
866 | interface. | |
05336835 | 867 | |
a8ac4ab3 | 868 | There are four roles: |
05336835 | 869 | |
4885bff7 TL |
870 | Administrator:: |
871 | ||
eb269701 | 872 | Is allowed to manage settings of {pmg}, excluding some tasks like network |
4885bff7 TL |
873 | configuration and upgrading. |
874 | ||
875 | Quarantine manager:: | |
05336835 | 876 | |
05336835 DC |
877 | Is allowed to manage quarantines, blacklists and whitelists, but not other |
878 | settings. Has no right to view any other data. | |
879 | ||
4885bff7 TL |
880 | Auditor:: |
881 | ||
05336835 DC |
882 | With this role, the user is only allowed to view data and configuration, but |
883 | not to edit it. | |
884 | ||
a8ac4ab3 TL |
885 | Helpdesk:: |
886 | ||
887 | Combines permissions of the 'Auditor' and the 'Quarantine Manager' role. | |
888 | ||
eb269701 | 889 | In addition, there is always the 'root' user, which is used to perform special |
4885bff7 TL |
890 | system administrator tasks, such as upgrading a host or changing the network |
891 | configuration. | |
05336835 | 892 | |
eb269701 DW |
893 | NOTE: Only PAM users are able to log in via the web interface and ssh, while the |
894 | users created through the web interface are not. Those users are created for | |
895 | {pmg} administration only. | |
05336835 DC |
896 | |
897 | Local user related settings are saved in `/etc/pmg/user.conf`. | |
898 | ||
eb269701 | 899 | For details on the fields, see xref:pmg_user_configuration_file[user.conf] |
05336835 | 900 | |
4a08dffe | 901 | [[pmgconfig_ldap]] |
05336835 DC |
902 | LDAP/Active Directory |
903 | ~~~~~~~~~~~~~~~~~~~~~ | |
904 | ||
a695a527 | 905 | [thumbnail="pmg-gui-ldap-user-config.png", big=1] |
f02d2b90 | 906 | |
05336835 DC |
907 | You can specify multiple LDAP/Active Directory profiles, so that you can |
908 | create rules matching those users and groups. | |
909 | ||
910 | Creating a profile requires (at least) the following: | |
911 | ||
912 | * profile name | |
913 | * protocol (LDAP or LDAPS; LDAPS is recommended) | |
914 | * at least one server | |
eb269701 | 915 | * a username and password (if your server does not support anonymous binds) |
05336835 DC |
916 | |
917 | All other fields should work with the defaults for most setups, but can be | |
918 | used to customize the queries. | |
919 | ||
920 | The settings are saved to `/etc/pmg/ldap.conf`. Details for the options | |
921 | can be found here: xref:pmg_ldap_configuration_file[ldap.conf] | |
922 | ||
923 | Bind user | |
924 | ^^^^^^^^^ | |
925 | ||
926 | It is highly recommended that the user which you use for connecting to the | |
eb269701 | 927 | LDAP server only has permission to query the server. For LDAP servers |
05336835 | 928 | (for example OpenLDAP or FreeIPA), the username has to be of a format like |
eb269701 DW |
929 | 'uid=username,cn=users,cn=accounts,dc=domain', where the specific fields |
930 | depend on your setup. For Active Directory servers, the format should be | |
05336835 DC |
931 | like 'username@domain' or 'domain\username'. |
932 | ||
933 | Sync | |
934 | ^^^^ | |
935 | ||
eb269701 DW |
936 | {pmg} synchronizes the relevant user and group information periodically, so that |
937 | the information is quickly available, even when the LDAP/AD server is | |
938 | temporarily inaccessible. | |
05336835 | 939 | |
3f18659b | 940 | After a successful sync, the groups and users should be visible on the web |
eb269701 | 941 | interface. Following this, you can create rules targeting LDAP users and groups. |
c331641e DM |
942 | |
943 | ||
4a08dffe | 944 | [[pmgconfig_fetchmail]] |
8538d9a2 | 945 | Fetchmail |
05336835 DC |
946 | ~~~~~~~~~ |
947 | ||
a695a527 | 948 | [thumbnail="pmg-gui-fetchmail-config.png", big=1] |
f02d2b90 | 949 | |
eb269701 | 950 | Fetchmail is a utility for polling and forwarding emails. You can define |
3f18659b | 951 | email accounts, which will then be fetched and forwarded to the email |
05336835 DC |
952 | address you defined. |
953 | ||
954 | You have to add an entry for each account/target combination you want to | |
eb269701 | 955 | fetch and forward. These will then be regularly polled and forwarded, |
05336835 DC |
956 | according to your configuration. |
957 | ||
eb269701 | 958 | The API and web interface offer the following configuration options: |
8538d9a2 DM |
959 | |
960 | include::fetchmail.conf.5-opts.adoc[] | |
961 | ||
962 | ||
e62ceaf0 DM |
963 | ifdef::manvolnum[] |
964 | include::pmg-copyright.adoc[] | |
965 | endif::manvolnum[] | |
966 |