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