]>
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 | |
29 | Interface (GUI), but it is also possible to directly edit the | |
30 | configuration files, use the REST API over 'https' | |
31 | or the command line tool `pmgsh`. | |
32 | ||
33 | The command line tool `pmgconfig` is used to simplify some common | |
34 | configuration tasks, i.e. to generate cerificates and to rewrite | |
35 | service configuration files. | |
36 | ||
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 | ||
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 | ||
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 | ||
76 | `/etc/pmg/fetchmailrc`:: | |
77 | ||
78 | Fetchmail configuration (POP3 and IMAP setup). | |
79 | ||
80 | `/etc/pmg/ldap.conf`:: | |
81 | ||
82 | LDAP configuration. | |
83 | ||
84 | `/etc/pmg/mynetworks`:: | |
85 | ||
86 | List of local (trusted) networks. | |
87 | ||
88 | `/etc/pmg/subscription`:: | |
89 | ||
90 | Stores your subscription key and status. | |
91 | ||
92 | `/etc/pmg/transports`:: | |
93 | ||
94 | Message delivery transport setup. | |
95 | ||
96 | `/etc/pmg/user.conf`:: | |
97 | ||
98 | GUI user configuration. | |
99 | ||
100 | `/etc/mail/spamassassin/custom.cf`:: | |
101 | ||
102 | Custom {spamassassin} setup. | |
103 | ||
104 | ||
105 | Keys and Certificates | |
106 | --------------------- | |
107 | ||
108 | `/etc/pmg/pmg-api.pem`:: | |
109 | ||
110 | Key and certificate (combined) used be the HTTPs server (API). | |
111 | ||
112 | `/etc/pmg/pmg-authkey.key`:: | |
113 | ||
114 | Privat key use to generate authentication tickets. | |
115 | ||
116 | `/etc/pmg/pmg-authkey.pub`:: | |
117 | ||
118 | Public key use to verify authentication tickets. | |
119 | ||
120 | `/etc/pmg/pmg-csrf.key`:: | |
121 | ||
122 | Internally used to generate CSRF tokens. | |
123 | ||
124 | `/etc/pmg/pmg-tls.pem`:: | |
125 | ||
126 | Key and certificate (combined) to encrypt mail traffic (TLS). | |
127 | ||
128 | ||
129 | Service Configuration Templates | |
130 | ------------------------------- | |
131 | ||
132 | {pmg} uses various services to implement mail filtering, for example | |
133 | the {postfix} Mail Transport Agent (MTA), the {clamav} antivirus | |
134 | engine and the Apache {spamassassin} project. Those services use | |
135 | separate configuration files, so we need to rewrite those files when | |
136 | configuration is changed. | |
137 | ||
138 | We use a template based approach to generate those files. The {tts} is | |
139 | a well known, fast and flexible template processing system. You can | |
140 | find the default templates in `/var/lib/pmg/templates/`. Please do not | |
141 | modify them directly, because your modification would get lost on the | |
142 | next update. Instead, copy them to `/etc/pmg/templates/`, then apply | |
143 | your changes there. | |
144 | ||
145 | Templates can access any configuration setting, and you can use the | |
146 | `pmgconfig dump` command to get a list of all variable names: | |
147 | ||
148 | ---- | |
149 | # pmgconfig dump | |
150 | ... | |
151 | dns.domain = yourdomain.tld | |
152 | dns.hostname = pmg | |
153 | ipconfig.int_ip = 192.168.2.127 | |
154 | pmg.admin.advfilter = 1 | |
155 | ... | |
156 | ---- | |
157 | ||
158 | The same tool is used to force regeneration of all template based | |
159 | configuration files. You need to run that after modifying a template, | |
160 | or when you directly edit configuration files | |
161 | ||
162 | ---- | |
163 | # pmgconfig sync --restart 1 | |
164 | ---- | |
165 | ||
166 | Above commands also restarts services if underlying configuration | |
167 | files are changed. Please note that this is automatically done when | |
168 | you change the configuration using the GUI or API. | |
169 | ||
170 | NOTE: Modified templates from `/etc/pmg/templates/` are automatically | |
171 | synced from the master node to all cluster members. | |
172 | ||
173 | ||
174 | System Configuration | |
175 | -------------------- | |
176 | ||
177 | Network and Time | |
178 | ~~~~~~~~~~~~~~~~ | |
179 | ||
180 | ifndef::manvolnum[] | |
181 | image::images/screenshot/pmg-gui-network-config.png[] | |
182 | endif::manvolnum[] | |
183 | ||
184 | Normally the network and time is already configured when you visit the | |
185 | GUI. The installer asks for those setting and sets up the correct | |
186 | values. | |
187 | ||
188 | The default setup uses a single Ethernet adapter and static IP | |
189 | assignment. The configuration is stored at '/etc/network/interfaces', | |
190 | and the actual network setup is done the standard Debian way using | |
191 | package 'ifupdown'. | |
192 | ||
193 | .Example network setup '/etc/network/interfaces' | |
194 | ---- | |
195 | source /etc/network/interfaces.d/* | |
196 | ||
197 | auto lo | |
198 | iface lo inet loopback | |
199 | ||
200 | auto ens18 | |
201 | iface ens18 inet static | |
202 | address 192.168.2.127 | |
203 | netmask 255.255.240.0 | |
204 | gateway 192.168.2.1 | |
205 | ---- | |
206 | ||
207 | .DNS recommendations | |
208 | ||
209 | Many tests to detect SPAM mails use DNS queries, so it is important to | |
210 | have a fast and reliable DNS server. We also query some public | |
211 | available DNS Blacklists. Most of them apply rate limits for clients, | |
212 | so they simply will not work if you use a public DNS server (because | |
213 | they are usually blocked). We recommend to use your own DNS server, | |
214 | which need to be configured in 'recursive' mode. | |
215 | ||
216 | ||
217 | Options | |
218 | ~~~~~~~ | |
219 | ||
220 | ifndef::manvolnum[] | |
221 | image::images/screenshot/pmg-gui-system-options.png[] | |
222 | endif::manvolnum[] | |
223 | ||
224 | ||
225 | Those settings are saved to subsection 'admin' in `/etc/pmg/pmg.conf`, | |
226 | using the following configuration keys: | |
227 | ||
228 | include::pmg.admin-conf-opts.adoc[] | |
229 | ||
230 | ||
231 | Mail Proxy Configuration | |
232 | ------------------------ | |
233 | ||
234 | Relaying | |
235 | ~~~~~~~~ | |
236 | ||
237 | ifndef::manvolnum[] | |
238 | image::images/screenshot/pmg-gui-mailproxy-relaying.png[] | |
239 | endif::manvolnum[] | |
240 | ||
241 | Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`, | |
242 | using the following configuration keys: | |
243 | ||
244 | include::pmg.mail-relaying-conf-opts.adoc[] | |
245 | ||
246 | Relay Domains | |
247 | ~~~~~~~~~~~~~ | |
248 | ||
249 | ifndef::manvolnum[] | |
250 | image::images/screenshot/pmg-gui-mailproxy-relaydomains.png[] | |
251 | endif::manvolnum[] | |
252 | ||
253 | List of relayed mail domains, i.e. what destination domains this | |
254 | system will relay mail to. The system will reject incoming mails to | |
255 | other domains. | |
256 | ||
257 | ||
258 | Ports | |
259 | ~~~~~ | |
260 | ||
261 | ifndef::manvolnum[] | |
262 | image::images/screenshot/pmg-gui-mailproxy-ports.png[] | |
263 | endif::manvolnum[] | |
264 | ||
265 | Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`, | |
266 | using the following configuration keys: | |
267 | ||
268 | include::pmg.mail-ports-conf-opts.adoc[] | |
269 | ||
270 | ||
271 | Options | |
272 | ~~~~~~~ | |
273 | ||
274 | ifndef::manvolnum[] | |
275 | image::images/screenshot/pmg-gui-mailproxy-options.png[] | |
276 | endif::manvolnum[] | |
277 | ||
278 | Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`, | |
279 | using the following configuration keys: | |
280 | ||
281 | include::pmg.mail-options-conf-opts.adoc[] | |
282 | ||
283 | ||
284 | Transports | |
285 | ~~~~~~~~~~ | |
286 | ||
287 | ifndef::manvolnum[] | |
288 | image::images/screenshot/pmg-gui-mailproxy-transports.png[] | |
289 | endif::manvolnum[] | |
290 | ||
291 | You can use {pmg} to send e-mails to different internal | |
292 | e-mail servers. For example you can send e-mails addressed to | |
293 | domain.com to your first e-mail server, and e-mails addressed to | |
294 | subdomain.domain.com to a second one. | |
295 | ||
296 | You can add the IP addresses, hostname and SMTP ports and mail domains (or | |
297 | just single email addresses) of your additional e-mail servers. | |
298 | ||
299 | ||
300 | Networks | |
301 | ~~~~~~~~ | |
302 | ||
303 | ifndef::manvolnum[] | |
304 | image::images/screenshot/pmg-gui-mailproxy-networks.png[] | |
305 | endif::manvolnum[] | |
306 | ||
307 | You can add additional internal (trusted) IP networks or hosts. | |
308 | All hosts in this list are allowed to relay. | |
309 | ||
310 | NOTE: Hosts in the same subnet with Proxmox can relay by default and | |
311 | it’s not needed to add them in this list. | |
312 | ||
313 | ||
314 | TLS | |
315 | ~~~ | |
316 | ||
317 | ifndef::manvolnum[] | |
318 | image::images/screenshot/pmg-gui-mailproxy-tls.png[] | |
319 | endif::manvolnum[] | |
320 | ||
321 | Transport Layer Security (TLS) provides certificate-based | |
322 | authentication and encrypted sessions. An encrypted session protects | |
323 | the information that is transmitted with SMTP mail. When you activate | |
324 | TLS, {pmg} automatically generates a new self signed | |
325 | certificate for you (`/etc/pmg/pmg-tls.pem`). | |
326 | ||
327 | {pmg} uses opportunistic TLS encryption. The SMTP transaction is | |
328 | encrypted if the 'STARTTLS' ESMTP feature is supported by the remote | |
329 | server. Otherwise, messages are sent in the clear. | |
330 | ||
331 | Enable TLS logging:: | |
332 | ||
333 | To get additional information about SMTP TLS activity you can enable | |
334 | TLS logging. That way information about TLS sessions and used | |
335 | certificate’s is logged via syslog. | |
336 | ||
337 | Add TLS received header:: | |
338 | ||
339 | Set this option to include information about the protocol and cipher | |
340 | used as well as the client and issuer CommonName into the "Received:" | |
341 | message header. | |
342 | ||
343 | Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`, | |
344 | using the following configuration keys: | |
345 | ||
346 | include::pmg.mail-tls-conf-opts.adoc[] | |
347 | ||
348 | ||
349 | Whitelist | |
350 | ~~~~~~~~~ | |
351 | ||
352 | ifndef::manvolnum[] | |
353 | image::images/screenshot/pmg-gui-mailproxy-whitelist.png[] | |
354 | endif::manvolnum[] | |
355 | ||
356 | All SMTP checks are disabled for those entries (e. g. Greylisting, | |
357 | SPF, RBL, ...) | |
358 | ||
359 | NOTE: If you use a backup MX server (e.g. your ISP offers this service | |
360 | for you) you should always add those servers here. | |
361 | ||
362 | ||
363 | Spam Detector Configuration | |
364 | --------------------------- | |
365 | ||
366 | Options | |
367 | ~~~~~~~ | |
368 | ||
369 | ifndef::manvolnum[] | |
370 | image::images/screenshot/pmg-gui-spam-options.png[] | |
371 | endif::manvolnum[] | |
372 | ||
373 | {pmg} uses a wide variety of local and network tests to identify spam | |
374 | signatures. This makes it harder for spammers to identify one aspect | |
375 | which they can craft their messages to work around the spam filter. | |
376 | ||
377 | Every single e-mail will be analyzed and gets a spam score | |
378 | assigned. The system attempts to optimize the efficiency of the rules | |
379 | that are run in terms of minimizing the number of false positives and | |
380 | false negatives. | |
381 | ||
382 | include::pmg.spam-conf-opts.adoc[] | |
383 | ||
384 | ||
385 | Quarantine | |
386 | ~~~~~~~~~~ | |
387 | ||
388 | ifndef::manvolnum[] | |
389 | image::images/screenshot/pmg-gui-spamquar-options.png[] | |
390 | endif::manvolnum[] | |
391 | ||
392 | Proxmox analyses all incoming e-mail messages and decides for each | |
393 | e-mail if its ham or spam (or virus). Good e-mails are delivered to | |
394 | the inbox and spam messages can be moved into the spam quarantine. | |
395 | ||
396 | The system can be configured to send daily reports to inform users | |
397 | about the personal spam messages received the last day. That report is | |
398 | only sent if there are new messages in the quarantine. | |
399 | ||
400 | include::pmg.spamquar-conf-opts.adoc[] | |
401 | ||
402 | ||
403 | Virus Detector Configuration | |
404 | ---------------------------- | |
405 | ||
406 | Options | |
407 | ~~~~~~~ | |
408 | ||
409 | ifndef::manvolnum[] | |
410 | image::images/screenshot/pmg-gui-virus-options.png[] | |
411 | endif::manvolnum[] | |
412 | ||
413 | All mails are automatically passed to the included virus detector | |
414 | ({clamav}). The default setting are considered safe, so it is usually | |
415 | not required to change them. | |
416 | ||
417 | {clamav} related settings are saved to subsection 'clamav' in `/etc/pmg/pmg.conf`, | |
418 | using the following configuration keys: | |
419 | ||
420 | include::pmg.clamav-conf-opts.adoc[] | |
421 | ||
422 | ifndef::manvolnum[] | |
423 | image::images/screenshot/pmg-gui-clamav-database.png[] | |
424 | endif::manvolnum[] | |
425 | ||
426 | Please note that the virus signature database it automatically | |
427 | updated. But you can see the database status on the GUI, and you can | |
428 | trigger manual updates there. | |
429 | ||
430 | ||
431 | Quarantine | |
432 | ~~~~~~~~~~ | |
433 | ||
434 | ifndef::manvolnum[] | |
435 | image::images/screenshot/pmg-gui-virusquar-options.png[] | |
436 | endif::manvolnum[] | |
437 | ||
438 | Indentified virus mails are automatically moved to the virus | |
439 | quarantine. The administartor can view those mails using the GUI, or | |
440 | deliver them in case of false positives. {pmg} does not notify | |
441 | individual users about received virus mails. | |
442 | ||
443 | Virus quarantine related settings are saved to subsection 'virusquar' | |
444 | in `/etc/pmg/pmg.conf`, using the following configuration keys: | |
445 | ||
446 | include::pmg.virusquar-conf-opts.adoc[] | |
447 | ||
448 | ||
449 | Custom SpamAssassin configuration | |
450 | --------------------------------- | |
451 | ||
452 | This is only for advanced users. To add or change the Proxmox | |
453 | {spamassassin} configuration please login to the console via SSH. Go | |
454 | to directory `/etc/mail/spamassasin/`. In this directory there are several | |
455 | files (`init.pre`, `local.cf`, ...) – do not change them. | |
456 | ||
457 | To add your special configuration, you have to create a new file and | |
458 | name it `custom.cf` (in this directory), then add your | |
459 | configuration there. Be aware to use the {spamassassin} | |
460 | syntax, and test with | |
461 | ||
462 | ---- | |
463 | # spamassassin -D --lint | |
464 | ---- | |
465 | ||
466 | If you run a cluster, the `custom.cf` file is synchronized from the | |
467 | master node to all cluster members. | |
468 | ||
469 | ||
470 | User Management | |
471 | --------------- | |
472 | ||
473 | User management in {pmg} consists of three types of users/accounts: | |
474 | ||
475 | ||
476 | Local Users | |
477 | ~~~~~~~~~~~ | |
478 | ||
479 | image::images/screenshot/pmg-gui-local-user-config.png[] | |
480 | ||
481 | Local users are used to manage and audit {pmg}. Those users can login on the | |
482 | management web interface. | |
483 | ||
484 | There are three roles: | |
485 | ||
486 | * Administrator | |
487 | + | |
488 | Is allowed to manage settings of {pmg}, except some tasks like | |
489 | network configuration and upgrading. | |
490 | ||
491 | * Quarantine manager | |
492 | + | |
493 | Is allowed to manage quarantines, blacklists and whitelists, but not other | |
494 | settings. Has no right to view any other data. | |
495 | ||
496 | * Auditor | |
497 | + | |
498 | With this role, the user is only allowed to view data and configuration, but | |
499 | not to edit it. | |
500 | ||
501 | In addition there is always the 'root' user, which is used to perform special | |
502 | system administrator tasks, such as updgrading a host or changing the | |
503 | network configuration. | |
504 | ||
505 | NOTE: Only pam users are able to login via the webconsole and ssh, which the | |
506 | users created with the web interface are not. Those users are created for | |
507 | {pmg} administration only. | |
508 | ||
509 | Local user related settings are saved in `/etc/pmg/user.conf`. | |
510 | ||
511 | For details of the fields see xref:pmg_user_configuration_file[user.conf] | |
512 | ||
513 | LDAP/Active Directory | |
514 | ~~~~~~~~~~~~~~~~~~~~~ | |
515 | ||
516 | image::images/screenshot/pmg-gui-ldap-user-config.png[] | |
517 | ||
518 | You can specify multiple LDAP/Active Directory profiles, so that you can | |
519 | create rules matching those users and groups. | |
520 | ||
521 | Creating a profile requires (at least) the following: | |
522 | ||
523 | * profile name | |
524 | * protocol (LDAP or LDAPS; LDAPS is recommended) | |
525 | * at least one server | |
526 | * a user and password (if your server does not support anonymous binds) | |
527 | ||
528 | All other fields should work with the defaults for most setups, but can be | |
529 | used to customize the queries. | |
530 | ||
531 | The settings are saved to `/etc/pmg/ldap.conf`. Details for the options | |
532 | can be found here: xref:pmg_ldap_configuration_file[ldap.conf] | |
533 | ||
534 | Bind user | |
535 | ^^^^^^^^^ | |
536 | ||
537 | It is highly recommended that the user which you use for connecting to the | |
538 | LDAP server only has the permission to query the server. For LDAP servers | |
539 | (for example OpenLDAP or FreeIPA), the username has to be of a format like | |
540 | 'uid=username,cn=users,cn=accounts,dc=domain' , where the specific fields are | |
541 | depending on your setup. For Active Directory servers, the format should be | |
542 | like 'username@domain' or 'domain\username'. | |
543 | ||
544 | Sync | |
545 | ^^^^ | |
546 | ||
547 | {pmg} synchronizes the relevant user and group info periodically, so that | |
548 | that information is available in a fast manner, even when the LDAP/AD server | |
549 | is temporarily not accessible. | |
550 | ||
551 | After a successfull sync, the groups and users should be visible on the web | |
552 | interface. After that, you can create rules targeting LDAP users and groups. | |
553 | ||
554 | ||
555 | Fetchmail | |
556 | ~~~~~~~~~ | |
557 | ||
558 | image::images/screenshot/pmg-gui-fetchmail-config.png[] | |
559 | ||
560 | Fetchmail is utility for polling and forwarding e-mails. You can define | |
561 | e-mail accounts, which will then be fetched and forwarded to the e-mail | |
562 | address you defined. | |
563 | ||
564 | You have to add an entry for each account/target combination you want to | |
565 | fetch and forward. Those will then be regularly polled and forwarded, | |
566 | according to your configuration. | |
567 | ||
568 | The API and web interface offer following configuration options: | |
569 | ||
570 | include::fetchmail.conf.5-opts.adoc[] | |
571 | ||
572 | ||
573 | ifdef::manvolnum[] | |
574 | include::pmg-copyright.adoc[] | |
575 | endif::manvolnum[] | |
576 |