9 pmgproxy - Proxmox Mail Gateway API Proxy Daemon
15 include::pmgproxy.8-synopsis.adoc[]
22 pmgproxy - Proxmox Mail Gateway API Proxy Daemon
23 ================================================
26 This daemon exposes the whole {pmg} API on TCP port 8006 using
27 HTTPS. It runs as user `www-data` and has very limited permissions.
28 Operations requiring more permissions are forwarded to the local
31 Requests targeted for other nodes are automatically forwarded to those
32 nodes. This means that you can manage your whole cluster by connecting
33 to a single {pmg} node.
35 Alternative HTTPS certificate
36 -----------------------------
38 By default, pmgproxy uses the certificate `/etc/pmg/pmg-api.pem` for HTTPS
39 connections. This certificate is self signed, and therefore not trusted by
40 browsers and operating systems by default. You can simply replace this
41 certificate with your own (include the key inside the '.pem' file) or obtain one
42 from an ACME enabled CA (configurable in the GUI).
44 Host based Access Control
45 -------------------------
47 It is possible to configure ``apache2''-like access control
48 lists. Values are read from file `/etc/default/pmgproxy`. For example:
51 ALLOW_FROM="10.0.0.1-10.0.0.5,192.168.0.0/22"
56 IP addresses can be specified using any syntax understood by `Net::IP`. The
57 name `all` is an alias for `0/0` and `::/0` (meaning all IPv4 and IPv6
60 The default policy is `allow`.
62 [width="100%",options="header"]
63 |===========================================================
64 | Match | POLICY=deny | POLICY=allow
65 | Match Allow only | allow | allow
66 | Match Deny only | deny | deny
67 | No match | deny | allow
68 | Match Both Allow & Deny | deny | allow
69 |===========================================================
75 By default the `pmgproxy` daemon listens on the wildcard address and accepts
76 connections from both IPv4 and IPv6 clients.
79 By setting `LISTEN_IP` in `/etc/default/pmgproxy` you can control to which IP
80 address the `pmgproxy` daemon binds. The IP-address needs to be configured on
83 Setting the `sysctl` `net.ipv6.bindv6only` to the non-default `1` will cause
84 the daemons to only accept connection from IPv6 clients, while usually also
85 causing lots of other issues. If you set this configuration we recommend to
86 either remove the `sysctl` setting, or set the `LISTEN_IP` to `0.0.0.0` (which
87 will only allow IPv4 clients).
89 `LISTEN_IP` can be used to only to restricting the socket to an internal
90 interface and thus have less exposure to the public internet, for example:
96 Similarly, you can also set an IPv6 address:
99 LISTEN_IP="2001:db8:85a3::1"
102 Note that if you want to specify a link-local IPv6 address, you need to provide
103 the interface name itself. For example:
106 LISTEN_IP="fe80::c463:8cff:feb9:6a4e%vmbr0"
109 WARNING: The nodes in a cluster need access to `pmgproxy` for communication,
110 possibly on different sub-nets. It is **not recommended** to set `LISTEN_IP` on
113 To apply the change you need to either reboot your node or fully restart the
117 systemctl restart pmgproxy.service
120 NOTE: Unlike `reload`, a `restart` of the pmgproxy service can interrupt some
121 long-running worker processes, for example a running console.So, please use a
122 maintenance window to bring this change in effect.
128 You can define the cipher list in `/etc/default/pmgproxy`, for example
130 CIPHERS="ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"
132 Above is the default. See the `ciphers(1)` man page from the `openssl`
133 package for a list of all available options.
135 The first of these ciphers, available to both the client and the `pmgproxy`,
138 Additionally you can allow the client to choose the cipher from the list above
139 by disabling the HONOR_CIPHER_ORDER option in `/etc/default/pmgproxy`:
144 Diffie-Hellman Parameters
145 -------------------------
147 You can define the used Diffie-Hellman parameters in
148 `/etc/default/pmgproxy` by setting `DHPARAMS` to the path of a file
149 containing DH parameters in PEM format, for example
151 DHPARAMS="/path/to/dhparams.pem"
153 If this option is not set, the built-in `skip2048` parameters will be
156 NOTE: DH parameters are only used if a cipher suite utilizing the DH key
157 exchange algorithm is negotiated.
162 By default `pmgproxy` uses gzip HTTP-level compression for compressible
163 content if the client supports it. This can be disabled in `/etc/default/pmgproxy`
168 include::pmg-copyright.adoc[]