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
 101 Keys and Certificates
 102 ---------------------
 103
 104 `/etc/pmg/pmg-api.pem`::
 105
 106 Key and certificate (combined) used be the HTTPs server (API).
 107
 108 `/etc/pmg/pmg-authkey.key`::
 109
 110 Privat key use to generate authentication tickets.
 111
 112 `/etc/pmg/pmg-authkey.pub`::
 113
 114 Public key use to verify authentication tickets.
 115
 116 `/etc/pmg/pmg-csrf.key`::
 117
 118 Internally used to generate CSRF tokens.
 119
 120 `/etc/pmg/pmg-tls.pem`::
 121
 122 Key and certificate (combined) to encrypt mail traffic (TLS).
 123
 124
 125 Service Configuration Templates
 126 -------------------------------
 127
 128 {pmg} uses various services to implement mail filtering, for example
 129 the {postfix} Mail Transport Agent (MTA), the {clamav} antivirus
 130 engine and the Apache {spamassassin} project. Those services use
 131 separate configuration files, so we need to rewrite those files when
 132 configuration is changed.
 133
 134 We use a template based approach to generate those files. The {tts} is
 135 a well known, fast and flexible template processing system. You can
 136 find the default templates in `/var/lib/pmg/templates/`. Please do not
 137 modify them directly, because your modification would get lost on the
 138 next update. Instead, copy them to `/etc/pmg/templates/`, then apply
 139 your changes there.
 140
 141 Templates can access any configuration setting, and you can use the
 142 `pmgconfig dump` command to get a list of all variable names:
 143
 144 ----
 145 # pmgconfig dump
 146 ...
 147 dns.domain = yourdomain.tld
 148 dns.hostname = pmg
 149 ipconfig.int_ip = 192.168.2.127
 150 pmg.admin.advfilter = 1
 151 ...
 152 ----
 153
 154 The same tool is used to force regeneration of all template based
 155 configuration files. You need to run that after modifying a template,
 156 or when you directly edit configuration files
 157
 158 ----
 159 # pmgconfig sync --restart 1
 160 ----
 161
 162 Above commands also restarts services if underlying configuration
 163 files are changed. Please note that this is automatically done when
 164 you change the configuration using the GUI or API.
 165
 166 NOTE: Modified templates from `/etc/pmg/templates/` are automatically
 167 synced from the master node to all cluster members.
 168
 169
 170 System Configuration
 171 --------------------
 172
 173 Network and Time
 174 ~~~~~~~~~~~~~~~~
 175
 176 ifndef::manvolnum[]
 177 image::images/screenshot/pmg-gui-network-config.png[]
 178 endif::manvolnum[]
 179
 180 Normally the network and time is already configured when you visit the
 181 GUI. The installer asks for those setting and sets up the correct
 182 values.
 183
 184 The default setup uses a single Ethernet adapter and static IP
 185 assignment. The configuration is stored at '/etc/network/interfaces',
 186 and the actual network setup is done the standard Debian way using
 187 package 'ifupdown'.
 188
 189 .Example network setup '/etc/network/interfaces'
 190 ----
 191 source /etc/network/interfaces.d/*
 192
 193 auto lo
 194 iface lo inet loopback
 195
 196 auto ens18
 197 iface ens18 inet static
 198         address  192.168.2.127
 199         netmask  255.255.240.0
 200         gateway  192.168.2.1
 201 ----
 202
 203 .DNS recommendations
 204
 205 Many tests to detect SPAM mails use DNS queries, so it is important to
 206 have a fast and reliable DNS server. We also query some public
 207 available DNS Blacklists. Most of them apply rate limits for clients,
 208 so they simply will not work if you use a public DNS server (because
 209 they are usually blocked). We recommend to use your own DNS server,
 210 which need to be configured in 'recursive' mode.
 211
 212
 213 Options
 214 ~~~~~~~
 215
 216 ifndef::manvolnum[]
 217 image::images/screenshot/pmg-gui-system-options.png[]
 218 endif::manvolnum[]
 219
 220 include::pmg.admin-conf-opts.adoc[]
 221
 222
 223 Backup and Restore
 224 ~~~~~~~~~~~~~~~~~~
 225
 226 ifndef::manvolnum[]
 227 image::images/screenshot/pmg-gui-backup.png[]
 228 endif::manvolnum[]
 229
 230 TODO
 231
 232
 233
 234 ifdef::manvolnum[]
 235 include::pmg-copyright.adoc[]
 236 endif::manvolnum[]
 237