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