]>
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 | ||
47 | Network setup. We never modify this files directly. Instead, we write | |
48 | changes to `/etc/network/interfaces.new`. When you reboot, we rename | |
49 | the file to `/etc/network/interfaces`, so any changes gets activated | |
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 | ||
66e9c719 DM |
112 | |
113 | Keys and Certificates | |
114 | --------------------- | |
115 | ||
116 | `/etc/pmg/pmg-api.pem`:: | |
117 | ||
118 | Key and certificate (combined) used be the HTTPs server (API). | |
119 | ||
120 | `/etc/pmg/pmg-authkey.key`:: | |
121 | ||
122 | Privat key use to generate authentication tickets. | |
123 | ||
124 | `/etc/pmg/pmg-authkey.pub`:: | |
125 | ||
126 | Public key use to verify authentication tickets. | |
127 | ||
128 | `/etc/pmg/pmg-csrf.key`:: | |
129 | ||
130 | Internally used to generate CSRF tokens. | |
131 | ||
132 | `/etc/pmg/pmg-tls.pem`:: | |
133 | ||
134 | Key and certificate (combined) to encrypt mail traffic (TLS). | |
135 | ||
5053eecc SI |
136 | `/etc/pmg/dkim/<selector>.private`:: |
137 | ||
138 | Key for DKIM signing mails with selector '<selector>'. | |
139 | ||
66e9c719 DM |
140 | |
141 | Service Configuration Templates | |
142 | ------------------------------- | |
143 | ||
9c85cc80 DM |
144 | {pmg} uses various services to implement mail filtering, for example |
145 | the {postfix} Mail Transport Agent (MTA), the {clamav} antivirus | |
146 | engine and the Apache {spamassassin} project. Those services use | |
147 | separate configuration files, so we need to rewrite those files when | |
148 | configuration is changed. | |
149 | ||
150 | We use a template based approach to generate those files. The {tts} is | |
151 | a well known, fast and flexible template processing system. You can | |
152 | find the default templates in `/var/lib/pmg/templates/`. Please do not | |
153 | modify them directly, because your modification would get lost on the | |
9dd45bd7 SI |
154 | next update. Instead, copy the template you wish to change to |
155 | `/etc/pmg/templates/`, then apply your changes there. | |
9c85cc80 DM |
156 | |
157 | Templates can access any configuration setting, and you can use the | |
158 | `pmgconfig dump` command to get a list of all variable names: | |
159 | ||
160 | ---- | |
161 | # pmgconfig dump | |
162 | ... | |
163 | dns.domain = yourdomain.tld | |
164 | dns.hostname = pmg | |
165 | ipconfig.int_ip = 192.168.2.127 | |
166 | pmg.admin.advfilter = 1 | |
167 | ... | |
168 | ---- | |
169 | ||
170 | The same tool is used to force regeneration of all template based | |
171 | configuration files. You need to run that after modifying a template, | |
172 | or when you directly edit configuration files | |
173 | ||
174 | ---- | |
175 | # pmgconfig sync --restart 1 | |
176 | ---- | |
177 | ||
9dd45bd7 | 178 | The above command also restarts services if the underlying configuration |
9c85cc80 DM |
179 | files are changed. Please note that this is automatically done when |
180 | you change the configuration using the GUI or API. | |
181 | ||
182 | NOTE: Modified templates from `/etc/pmg/templates/` are automatically | |
183 | synced from the master node to all cluster members. | |
66e9c719 DM |
184 | |
185 | ||
4a08dffe | 186 | [[pmgconfig_systemconfig]] |
685576c2 DM |
187 | System Configuration |
188 | -------------------- | |
189 | ||
190 | Network and Time | |
191 | ~~~~~~~~~~~~~~~~ | |
192 | ||
193 | ifndef::manvolnum[] | |
194 | image::images/screenshot/pmg-gui-network-config.png[] | |
195 | endif::manvolnum[] | |
196 | ||
45de5bf5 | 197 | Normally the network and time is already configured when you visit the |
c6e27848 | 198 | GUI. The installer asks for those settings and sets up the correct |
45de5bf5 DM |
199 | values. |
200 | ||
201 | The default setup uses a single Ethernet adapter and static IP | |
202 | assignment. The configuration is stored at '/etc/network/interfaces', | |
203 | and the actual network setup is done the standard Debian way using | |
204 | package 'ifupdown'. | |
205 | ||
206 | .Example network setup '/etc/network/interfaces' | |
207 | ---- | |
208 | source /etc/network/interfaces.d/* | |
209 | ||
210 | auto lo | |
211 | iface lo inet loopback | |
212 | ||
213 | auto ens18 | |
214 | iface ens18 inet static | |
215 | address 192.168.2.127 | |
216 | netmask 255.255.240.0 | |
217 | gateway 192.168.2.1 | |
218 | ---- | |
219 | ||
220 | .DNS recommendations | |
221 | ||
222 | Many tests to detect SPAM mails use DNS queries, so it is important to | |
223 | have a fast and reliable DNS server. We also query some public | |
224 | available DNS Blacklists. Most of them apply rate limits for clients, | |
225 | so they simply will not work if you use a public DNS server (because | |
226 | they are usually blocked). We recommend to use your own DNS server, | |
227 | which need to be configured in 'recursive' mode. | |
685576c2 DM |
228 | |
229 | ||
230 | Options | |
231 | ~~~~~~~ | |
232 | ||
233 | ifndef::manvolnum[] | |
234 | image::images/screenshot/pmg-gui-system-options.png[] | |
235 | endif::manvolnum[] | |
236 | ||
e09057ab DM |
237 | |
238 | Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`, | |
239 | using the following configuration keys: | |
240 | ||
685576c2 DM |
241 | include::pmg.admin-conf-opts.adoc[] |
242 | ||
c331641e DM |
243 | |
244 | Mail Proxy Configuration | |
245 | ------------------------ | |
246 | ||
4a08dffe | 247 | [[pmgconfig_mailproxy_relaying]] |
c331641e DM |
248 | Relaying |
249 | ~~~~~~~~ | |
250 | ||
c331641e DM |
251 | ifndef::manvolnum[] |
252 | image::images/screenshot/pmg-gui-mailproxy-relaying.png[] | |
253 | endif::manvolnum[] | |
254 | ||
e09057ab DM |
255 | Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`, |
256 | using the following configuration keys: | |
257 | ||
258 | include::pmg.mail-relaying-conf-opts.adoc[] | |
c331641e | 259 | |
4a08dffe | 260 | [[pmgconfig_mailproxy_relay_domains]] |
c331641e DM |
261 | Relay Domains |
262 | ~~~~~~~~~~~~~ | |
263 | ||
c331641e DM |
264 | ifndef::manvolnum[] |
265 | image::images/screenshot/pmg-gui-mailproxy-relaydomains.png[] | |
266 | endif::manvolnum[] | |
267 | ||
6822b369 DM |
268 | List of relayed mail domains, i.e. what destination domains this |
269 | system will relay mail to. The system will reject incoming mails to | |
270 | other domains. | |
c331641e | 271 | |
d9c56b22 | 272 | |
4a08dffe | 273 | [[pmgconfig_mailproxy_ports]] |
c331641e DM |
274 | Ports |
275 | ~~~~~ | |
276 | ||
c331641e DM |
277 | ifndef::manvolnum[] |
278 | image::images/screenshot/pmg-gui-mailproxy-ports.png[] | |
279 | endif::manvolnum[] | |
280 | ||
d9c56b22 DM |
281 | Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`, |
282 | using the following configuration keys: | |
283 | ||
284 | include::pmg.mail-ports-conf-opts.adoc[] | |
285 | ||
c331641e | 286 | |
4a08dffe | 287 | [[pmgconfig_mailproxy_options]] |
c331641e DM |
288 | Options |
289 | ~~~~~~~ | |
290 | ||
c331641e DM |
291 | ifndef::manvolnum[] |
292 | image::images/screenshot/pmg-gui-mailproxy-options.png[] | |
293 | endif::manvolnum[] | |
294 | ||
e3d778e0 DM |
295 | Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`, |
296 | using the following configuration keys: | |
297 | ||
298 | include::pmg.mail-options-conf-opts.adoc[] | |
c331641e DM |
299 | |
300 | ||
4a08dffe | 301 | [[pmgconfig_mailproxy_transports]] |
c331641e DM |
302 | Transports |
303 | ~~~~~~~~~~ | |
304 | ||
305 | ifndef::manvolnum[] | |
306 | image::images/screenshot/pmg-gui-mailproxy-transports.png[] | |
307 | endif::manvolnum[] | |
308 | ||
b335e06b DM |
309 | You can use {pmg} to send e-mails to different internal |
310 | e-mail servers. For example you can send e-mails addressed to | |
311 | domain.com to your first e-mail server, and e-mails addressed to | |
312 | subdomain.domain.com to a second one. | |
313 | ||
314 | You can add the IP addresses, hostname and SMTP ports and mail domains (or | |
315 | just single email addresses) of your additional e-mail servers. | |
c331641e DM |
316 | |
317 | ||
4a08dffe | 318 | [[pmgconfig_mailproxy_networks]] |
c331641e DM |
319 | Networks |
320 | ~~~~~~~~ | |
321 | ||
322 | ifndef::manvolnum[] | |
323 | image::images/screenshot/pmg-gui-mailproxy-networks.png[] | |
324 | endif::manvolnum[] | |
325 | ||
20e879ad DM |
326 | You can add additional internal (trusted) IP networks or hosts. |
327 | All hosts in this list are allowed to relay. | |
328 | ||
329 | NOTE: Hosts in the same subnet with Proxmox can relay by default and | |
330 | it’s not needed to add them in this list. | |
c331641e DM |
331 | |
332 | ||
4a08dffe | 333 | [[pmgconfig_mailproxy_tls]] |
c331641e DM |
334 | TLS |
335 | ~~~ | |
336 | ||
337 | ifndef::manvolnum[] | |
338 | image::images/screenshot/pmg-gui-mailproxy-tls.png[] | |
339 | endif::manvolnum[] | |
340 | ||
20e879ad DM |
341 | Transport Layer Security (TLS) provides certificate-based |
342 | authentication and encrypted sessions. An encrypted session protects | |
343 | the information that is transmitted with SMTP mail. When you activate | |
344 | TLS, {pmg} automatically generates a new self signed | |
345 | certificate for you (`/etc/pmg/pmg-tls.pem`). | |
346 | ||
37b2b051 | 347 | {pmg} uses opportunistic TLS encryption by default. The SMTP transaction is |
20e879ad | 348 | encrypted if the 'STARTTLS' ESMTP feature is supported by the remote |
37b2b051 SI |
349 | server. Otherwise, messages are sent in the clear. |
350 | You can set a different TLS policy per desitination domain, should you for | |
351 | example need to prevent e-mail delivery without encryption, or to work around | |
352 | a broken 'STARTTLS' ESMTP implementation. See {postfix_tls_readme} for details | |
353 | on the supported policies. | |
20e879ad DM |
354 | |
355 | Enable TLS logging:: | |
356 | ||
357 | To get additional information about SMTP TLS activity you can enable | |
358 | TLS logging. That way information about TLS sessions and used | |
359 | certificate’s is logged via syslog. | |
360 | ||
361 | Add TLS received header:: | |
362 | ||
363 | Set this option to include information about the protocol and cipher | |
364 | used as well as the client and issuer CommonName into the "Received:" | |
365 | message header. | |
366 | ||
a649b38f DM |
367 | Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`, |
368 | using the following configuration keys: | |
369 | ||
370 | include::pmg.mail-tls-conf-opts.adoc[] | |
371 | ||
c331641e | 372 | |
20522d96 SI |
373 | [[pmgconfig_mailproxy_dkim]] |
374 | DKIM Signing | |
375 | ~~~~~~~~~~~~ | |
376 | ||
377 | DomainKeys Identified Mail (DKIM) Signatures (see {dkim_rfc}) is a method to | |
378 | cryptographically authenticate a mail as originating from a particular domain. | |
379 | Before sending the mail a hash over certain header fields and the body is | |
380 | computed, signed with a private key and added in the `DKIM-Signature` header of | |
381 | the mail. The 'selector' (a short identifier chosen by you, used to identify | |
382 | which system and private key were used for signing) is also included in the | |
383 | `DKIM-Signature` header. | |
384 | ||
385 | The verification is done by the receiver: The public key is fetched | |
386 | via DNS TXT lookup for `yourselector._domainkey.yourdomain.example` and used | |
387 | for verifying the hash. You can publish multiple selectors for your domain, | |
388 | each use by a system which sends e-mail from your domain, without the need to | |
389 | share the private key. | |
390 | ||
391 | {pmg} verifies DKIM Signatures for inbound mail in the Spam Filter by default. | |
392 | ||
393 | Additionally it supports conditionally signing outbound mail if configured. | |
394 | It uses one private key and selector per PMG deployment (all nodes in a cluster | |
395 | use the same key). The key has a minimal size of 1024 bits and rsa-sha256 is | |
396 | used as signing algorithm. | |
397 | ||
398 | The headers included in the signature are taken from the list of | |
399 | `Mail::DKIM::Signer`. Additionally `Content-Type` (if present), `From`, `To`, | |
400 | `CC`, `Reply-To` and `Subject` get oversigned. | |
401 | ||
402 | You can either sign all mails received on the internal port using the domain of | |
403 | the envelope sender address or create a list of domains, for which e-mails | |
404 | should be signed, defaulting to the list of relay domains. | |
405 | ||
406 | ||
407 | Enable DKIM Signing:: | |
408 | ||
409 | Controls whether outbound mail should get DKIM signed. | |
410 | ||
411 | Selector:: | |
412 | ||
413 | The selector used for signing the mail. The private key used for signing is | |
3fe91910 | 414 | saved under `/etc/pmg/dkim/yourselector.private`. You can display the DNS TXT |
20522d96 SI |
415 | record which you need to add to all domains signed by {pmg} by clicking on the |
416 | 'View DNS Record' Button. | |
417 | ||
418 | Sign all Outgoing Mail:: | |
419 | ||
420 | Controls whether all outbound mail should get signed or only mails from domains | |
421 | listed in `/etc/pmg/dkim/domains` if it exists and `/etc/pmg/domains` otherwise. | |
422 | ||
423 | Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`, | |
424 | using the following configuration keys: | |
425 | ||
426 | include::pmg.admin-dkim-conf-opts.adoc[] | |
427 | ||
428 | ||
c331641e DM |
429 | Whitelist |
430 | ~~~~~~~~~ | |
431 | ||
432 | ifndef::manvolnum[] | |
433 | image::images/screenshot/pmg-gui-mailproxy-whitelist.png[] | |
434 | endif::manvolnum[] | |
435 | ||
6822b369 DM |
436 | All SMTP checks are disabled for those entries (e. g. Greylisting, |
437 | SPF, RBL, ...) | |
438 | ||
439 | NOTE: If you use a backup MX server (e.g. your ISP offers this service | |
440 | for you) you should always add those servers here. | |
c331641e DM |
441 | |
442 | ||
4a08dffe | 443 | [[pmgconfig_spamdetector]] |
c331641e DM |
444 | Spam Detector Configuration |
445 | --------------------------- | |
446 | ||
2d672352 DM |
447 | Options |
448 | ~~~~~~~ | |
449 | ||
74bfe8ba DM |
450 | ifndef::manvolnum[] |
451 | image::images/screenshot/pmg-gui-spam-options.png[] | |
452 | endif::manvolnum[] | |
453 | ||
3371c521 DM |
454 | {pmg} uses a wide variety of local and network tests to identify spam |
455 | signatures. This makes it harder for spammers to identify one aspect | |
456 | which they can craft their messages to work around the spam filter. | |
457 | ||
458 | Every single e-mail will be analyzed and gets a spam score | |
459 | assigned. The system attempts to optimize the efficiency of the rules | |
460 | that are run in terms of minimizing the number of false positives and | |
461 | false negatives. | |
462 | ||
463 | include::pmg.spam-conf-opts.adoc[] | |
464 | ||
465 | ||
4a08dffe | 466 | [[pmgconfig_spamdetector_quarantine]] |
2d672352 DM |
467 | Quarantine |
468 | ~~~~~~~~~~ | |
3371c521 | 469 | |
74bfe8ba DM |
470 | ifndef::manvolnum[] |
471 | image::images/screenshot/pmg-gui-spamquar-options.png[] | |
472 | endif::manvolnum[] | |
473 | ||
3371c521 DM |
474 | Proxmox analyses all incoming e-mail messages and decides for each |
475 | e-mail if its ham or spam (or virus). Good e-mails are delivered to | |
476 | the inbox and spam messages can be moved into the spam quarantine. | |
477 | ||
478 | The system can be configured to send daily reports to inform users | |
479 | about the personal spam messages received the last day. That report is | |
480 | only sent if there are new messages in the quarantine. | |
481 | ||
ee34edb0 DC |
482 | Some options are only available in the config file `/etc/pmg/pmg.conf`, |
483 | and not in the webinterface. | |
484 | ||
3371c521 | 485 | include::pmg.spamquar-conf-opts.adoc[] |
c331641e DM |
486 | |
487 | ||
4a08dffe | 488 | [[pmgconfig_clamav]] |
c331641e DM |
489 | Virus Detector Configuration |
490 | ---------------------------- | |
491 | ||
4a08dffe | 492 | [[pmgconfig_clamav_options]] |
2d672352 DM |
493 | Options |
494 | ~~~~~~~ | |
495 | ||
e7c18c7c DM |
496 | ifndef::manvolnum[] |
497 | image::images/screenshot/pmg-gui-virus-options.png[] | |
498 | endif::manvolnum[] | |
499 | ||
0bfbbf88 DM |
500 | All mails are automatically passed to the included virus detector |
501 | ({clamav}). The default setting are considered safe, so it is usually | |
502 | not required to change them. | |
503 | ||
504 | {clamav} related settings are saved to subsection 'clamav' in `/etc/pmg/pmg.conf`, | |
505 | using the following configuration keys: | |
506 | ||
507 | include::pmg.clamav-conf-opts.adoc[] | |
508 | ||
e7c18c7c DM |
509 | ifndef::manvolnum[] |
510 | image::images/screenshot/pmg-gui-clamav-database.png[] | |
511 | endif::manvolnum[] | |
512 | ||
513 | Please note that the virus signature database it automatically | |
514 | updated. But you can see the database status on the GUI, and you can | |
515 | trigger manual updates there. | |
516 | ||
0bfbbf88 | 517 | |
4a08dffe | 518 | [[pmgconfig_clamav_quarantine]] |
2d672352 DM |
519 | Quarantine |
520 | ~~~~~~~~~~ | |
0bfbbf88 | 521 | |
e7c18c7c DM |
522 | ifndef::manvolnum[] |
523 | image::images/screenshot/pmg-gui-virusquar-options.png[] | |
524 | endif::manvolnum[] | |
525 | ||
0bfbbf88 DM |
526 | Indentified virus mails are automatically moved to the virus |
527 | quarantine. The administartor can view those mails using the GUI, or | |
528 | deliver them in case of false positives. {pmg} does not notify | |
529 | individual users about received virus mails. | |
530 | ||
531 | Virus quarantine related settings are saved to subsection 'virusquar' | |
532 | in `/etc/pmg/pmg.conf`, using the following configuration keys: | |
533 | ||
534 | include::pmg.virusquar-conf-opts.adoc[] | |
c331641e DM |
535 | |
536 | ||
7eff8815 DM |
537 | Custom SpamAssassin configuration |
538 | --------------------------------- | |
539 | ||
833e1edc SI |
540 | This is only for advanced users. {spamassassin}'s rules and their associated |
541 | scores get updated regularly and are trained on a huge corpus, which gets | |
542 | classified by experts. In most cases adding a rule for matching a particular | |
543 | keyword is the wrong approach, leading to many false positives. Usually bad | |
544 | detection rates are better addressed by properly setting up DNS than by adding | |
545 | a custom rule - watch out for matches to 'URIBL_BLOCKED' in the logs or | |
546 | spam-headers - see the {spamassassin_dnsbl}. | |
547 | ||
548 | To add or change the Proxmox {spamassassin} configuration please login to the | |
d2f49775 TL |
549 | console via SSH. Change to the `/etc/mail/spamassassin/` directory. In this |
550 | directory there are several files (`init.pre`, `local.cf`, ...) - do not change | |
551 | them, as they will be overwritten by any {spamassassin} rule update. | |
833e1edc SI |
552 | |
553 | To add your special configuration, you have to create a new file and name it | |
d2f49775 TL |
554 | `custom.cf` (in this directory), then add your configuration there. Make sure |
555 | to use the correct {spamassassin} syntax, and test with | |
7eff8815 DM |
556 | |
557 | ---- | |
558 | # spamassassin -D --lint | |
559 | ---- | |
560 | ||
561 | If you run a cluster, the `custom.cf` file is synchronized from the | |
d2f49775 | 562 | master node to all cluster members automatically. |
7eff8815 DM |
563 | |
564 | ||
ed7970d8 SI |
565 | [[pmgconfig_custom_check]] |
566 | Custom Check Interface | |
567 | ---------------------- | |
568 | ||
569 | For use cases which are not handled by the {pmg} Virus Detector and | |
570 | {spamassassin} configuration, advanced users can create a custom check | |
571 | executable which, if enabled will be called before the Virus Detector and before | |
572 | passing an e-mail through the Rule System. The custom check API is kept as | |
573 | simple as possible, while still providing a great deal of control over the | |
574 | treatment of an e-mail. Its input is passed via two CLI arguments: | |
575 | ||
576 | * the 'api-version' (currently `v1`) - for potential future change of the | |
577 | invocation | |
578 | ||
579 | * the 'queue-file-name' - a filename, which contains the complete e-mail as | |
580 | rfc822/eml file | |
581 | ||
582 | The expected output need to be printed on STDOUT and consists of two lines: | |
583 | ||
584 | * the 'api-version' (currently 'v1') - see above | |
585 | ||
586 | * one of the following 3 results: | |
587 | ** 'OK' - e-mail is ok | |
588 | ** 'VIRUS: <virusdescription>' - e-mail is treated as if it contained a virus | |
589 | (the virusdescription is logged and added to the e-mail's headers) | |
590 | ** 'SCORE: <number>' - <number> is added (negative numbers are also possible) | |
591 | to the e-mail's spamscore | |
592 | ||
593 | The check is run with a 5 minute timeout - if it is exceeded the check | |
594 | executable is killed and the e-mail is treated as OK. | |
595 | ||
596 | All output written to STDERR by the check is written with priority 'err' to the | |
597 | journal/mail.log. | |
598 | ||
599 | A simple sample script following the API (and yielding a random result) for | |
600 | reference: | |
601 | ||
602 | ---- | |
603 | #!/bin/sh | |
604 | ||
605 | echo "called with $*" 1>&2 | |
606 | ||
607 | if [ "$#" -ne 2 ]; then | |
608 | echo "usage: $0 APIVERSION QUEUEFILENAME" 1>&2 | |
609 | exit 1 | |
610 | fi | |
611 | ||
612 | apiver="$1" | |
613 | shift | |
614 | ||
615 | if [ "$apiver" != "v1" ]; then | |
616 | echo "wrong APIVERSION: $apiver" 1>&2 | |
617 | exit 2 | |
618 | fi | |
619 | ||
620 | queue_file="$1" | |
621 | ||
622 | echo "v1" | |
623 | ||
624 | choice=$(shuf -i 0-3 -n1) | |
625 | ||
626 | case "$choice" in | |
627 | 0) | |
628 | echo OK | |
629 | ;; | |
630 | 1) | |
631 | echo SCORE: 4 | |
632 | ;; | |
633 | 2) | |
634 | echo VIRUS: Random Virus | |
635 | ;; | |
636 | 3) #timeout-test | |
637 | for i in $(seq 1 7); do | |
638 | echo "custom checking mail: $queue_file - minute $i" 1>&2 | |
639 | sleep 60 | |
640 | done | |
641 | ;; | |
642 | esac | |
643 | ||
644 | exit 0 | |
645 | ---- | |
646 | ||
647 | The custom check needs to be enabled in the admin section of `/etc/pmg/pmg.conf` | |
648 | ||
649 | ---- | |
650 | section: admin | |
651 | custom_check 1 | |
652 | ---- | |
653 | ||
654 | The location of the custom check executable can also be set there with the key | |
655 | `custom_check_path` and defaults to `/usr/local/bin/pmg-custom-check`. | |
656 | ||
657 | ||
c331641e DM |
658 | User Management |
659 | --------------- | |
660 | ||
05336835 DC |
661 | User management in {pmg} consists of three types of users/accounts: |
662 | ||
663 | ||
4a08dffe | 664 | [[pmgconfig_localuser]] |
05336835 DC |
665 | Local Users |
666 | ~~~~~~~~~~~ | |
667 | ||
f02d2b90 DM |
668 | image::images/screenshot/pmg-gui-local-user-config.png[] |
669 | ||
05336835 DC |
670 | Local users are used to manage and audit {pmg}. Those users can login on the |
671 | management web interface. | |
672 | ||
673 | There are three roles: | |
674 | ||
675 | * Administrator | |
676 | + | |
677 | Is allowed to manage settings of {pmg}, except some tasks like | |
678 | network configuration and upgrading. | |
679 | ||
680 | * Quarantine manager | |
681 | + | |
682 | Is allowed to manage quarantines, blacklists and whitelists, but not other | |
683 | settings. Has no right to view any other data. | |
684 | ||
685 | * Auditor | |
686 | + | |
687 | With this role, the user is only allowed to view data and configuration, but | |
688 | not to edit it. | |
689 | ||
690 | In addition there is always the 'root' user, which is used to perform special | |
691 | system administrator tasks, such as updgrading a host or changing the | |
692 | network configuration. | |
693 | ||
694 | NOTE: Only pam users are able to login via the webconsole and ssh, which the | |
695 | users created with the web interface are not. Those users are created for | |
696 | {pmg} administration only. | |
697 | ||
698 | Local user related settings are saved in `/etc/pmg/user.conf`. | |
699 | ||
700 | For details of the fields see xref:pmg_user_configuration_file[user.conf] | |
701 | ||
4a08dffe | 702 | [[pmgconfig_ldap]] |
05336835 DC |
703 | LDAP/Active Directory |
704 | ~~~~~~~~~~~~~~~~~~~~~ | |
705 | ||
f02d2b90 DM |
706 | image::images/screenshot/pmg-gui-ldap-user-config.png[] |
707 | ||
05336835 DC |
708 | You can specify multiple LDAP/Active Directory profiles, so that you can |
709 | create rules matching those users and groups. | |
710 | ||
711 | Creating a profile requires (at least) the following: | |
712 | ||
713 | * profile name | |
714 | * protocol (LDAP or LDAPS; LDAPS is recommended) | |
715 | * at least one server | |
716 | * a user and password (if your server does not support anonymous binds) | |
717 | ||
718 | All other fields should work with the defaults for most setups, but can be | |
719 | used to customize the queries. | |
720 | ||
721 | The settings are saved to `/etc/pmg/ldap.conf`. Details for the options | |
722 | can be found here: xref:pmg_ldap_configuration_file[ldap.conf] | |
723 | ||
724 | Bind user | |
725 | ^^^^^^^^^ | |
726 | ||
727 | It is highly recommended that the user which you use for connecting to the | |
728 | LDAP server only has the permission to query the server. For LDAP servers | |
729 | (for example OpenLDAP or FreeIPA), the username has to be of a format like | |
730 | 'uid=username,cn=users,cn=accounts,dc=domain' , where the specific fields are | |
731 | depending on your setup. For Active Directory servers, the format should be | |
732 | like 'username@domain' or 'domain\username'. | |
733 | ||
734 | Sync | |
735 | ^^^^ | |
736 | ||
737 | {pmg} synchronizes the relevant user and group info periodically, so that | |
738 | that information is available in a fast manner, even when the LDAP/AD server | |
739 | is temporarily not accessible. | |
740 | ||
741 | After a successfull sync, the groups and users should be visible on the web | |
742 | interface. After that, you can create rules targeting LDAP users and groups. | |
c331641e DM |
743 | |
744 | ||
4a08dffe | 745 | [[pmgconfig_fetchmail]] |
8538d9a2 | 746 | Fetchmail |
05336835 DC |
747 | ~~~~~~~~~ |
748 | ||
f02d2b90 DM |
749 | image::images/screenshot/pmg-gui-fetchmail-config.png[] |
750 | ||
05336835 DC |
751 | Fetchmail is utility for polling and forwarding e-mails. You can define |
752 | e-mail accounts, which will then be fetched and forwarded to the e-mail | |
753 | address you defined. | |
754 | ||
755 | You have to add an entry for each account/target combination you want to | |
756 | fetch and forward. Those will then be regularly polled and forwarded, | |
757 | according to your configuration. | |
758 | ||
759 | The API and web interface offer following configuration options: | |
8538d9a2 DM |
760 | |
761 | include::fetchmail.conf.5-opts.adoc[] | |
762 | ||
763 | ||
e62ceaf0 DM |
764 | ifdef::manvolnum[] |
765 | include::pmg-copyright.adoc[] | |
766 | endif::manvolnum[] | |
767 |