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}
 117
 118
 119 System Configuration
 120 --------------------
 121
 122 Network and Time
 123 ~~~~~~~~~~~~~~~~
 124
 125 ifndef::manvolnum[]
 126 image::images/screenshot/pmg-gui-network-config.png[]
 127 endif::manvolnum[]
 128
 129 Normally the network and time is already configured when you visit the
 130 GUI. The installer asks for those setting and sets up the correct
 131 values.
 132
 133 The default setup uses a single Ethernet adapter and static IP
 134 assignment. The configuration is stored at '/etc/network/interfaces',
 135 and the actual network setup is done the standard Debian way using
 136 package 'ifupdown'.
 137
 138 .Example network setup '/etc/network/interfaces'
 139 ----
 140 source /etc/network/interfaces.d/*
 141
 142 auto lo
 143 iface lo inet loopback
 144
 145 auto ens18
 146 iface ens18 inet static
 147         address  192.168.2.127
 148         netmask  255.255.240.0
 149         gateway  192.168.2.1
 150 ----
 151
 152 .DNS recommendations
 153
 154 Many tests to detect SPAM mails use DNS queries, so it is important to
 155 have a fast and reliable DNS server. We also query some public
 156 available DNS Blacklists. Most of them apply rate limits for clients,
 157 so they simply will not work if you use a public DNS server (because
 158 they are usually blocked). We recommend to use your own DNS server,
 159 which need to be configured in 'recursive' mode.
 160
 161
 162 Options
 163 ~~~~~~~
 164
 165 ifndef::manvolnum[]
 166 image::images/screenshot/pmg-gui-system-options.png[]
 167 endif::manvolnum[]
 168
 169 include::pmg.admin-conf-opts.adoc[]
 170
 171
 172 Backup and Restore
 173 ~~~~~~~~~~~~~~~~~~
 174
 175 ifndef::manvolnum[]
 176 image::images/screenshot/pmg-gui-backup.png[]
 177 endif::manvolnum[]
 178
 179 TODO
 180
 181
 182
 183 ifdef::manvolnum[]
 184 include::pmg-copyright.adoc[]
 185 endif::manvolnum[]
 186