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