pmgconfig.adoc

   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
 250 ifndef::manvolnum[]
 251 image::images/screenshot/pmg-gui-mailproxy-relaydomains.png[]
 252 endif::manvolnum[]
 253
 254 TODO
 255
 256
 257 Ports
 258 ~~~~~
 259
 260 ifndef::manvolnum[]
 261 image::images/screenshot/pmg-gui-mailproxy-ports.png[]
 262 endif::manvolnum[]
 263
 264 Those settings are saved to subsection 'mail' in `/etc/pmg/pmg.conf`,
 265 using the following configuration keys:
 266
 267 include::pmg.mail-ports-conf-opts.adoc[]
 268
 269
 270 Options
 271 ~~~~~~~
 272
 273
 274 ifndef::manvolnum[]
 275 image::images/screenshot/pmg-gui-mailproxy-options.png[]
 276 endif::manvolnum[]
 277
 278 TODO
 279
 280
 281 Transports
 282 ~~~~~~~~~~
 283
 284 ifndef::manvolnum[]
 285 image::images/screenshot/pmg-gui-mailproxy-transports.png[]
 286 endif::manvolnum[]
 287
 288 TODO
 289
 290
 291 Networks
 292 ~~~~~~~~
 293
 294 ifndef::manvolnum[]
 295 image::images/screenshot/pmg-gui-mailproxy-networks.png[]
 296 endif::manvolnum[]
 297
 298 TODO
 299
 300
 301 TLS
 302 ~~~
 303
 304 ifndef::manvolnum[]
 305 image::images/screenshot/pmg-gui-mailproxy-tls.png[]
 306 endif::manvolnum[]
 307
 308 TODO
 309
 310 Whitelist
 311 ~~~~~~~~~
 312
 313 ifndef::manvolnum[]
 314 image::images/screenshot/pmg-gui-mailproxy-whitelist.png[]
 315 endif::manvolnum[]
 316
 317 TODO
 318
 319
 320 Spam Detector Configuration
 321 ---------------------------
 322
 323 TODO
 324
 325
 326 Virus Detector Configuration
 327 ----------------------------
 328
 329 TODO
 330
 331
 332 User Management
 333 ---------------
 334
 335 TODO
 336
 337
 338 ifdef::manvolnum[]
 339 include::pmg-copyright.adoc[]
 340 endif::manvolnum[]
 341