pmgproxy(8)

NAME

pmgproxy - Proxmox Mail Gateway API Proxy Daemon

SYNOPSIS

pmgproxy <COMMAND> [ARGS] [OPTIONS]

pmgproxy help [OPTIONS]

Get help about specified command.

--extra-args <array>: Shows help for a specific command
--verbose <boolean>: Verbose output format.

pmgproxy restart

Restart the daemon (or start if not running).

pmgproxy start [OPTIONS]

Start the daemon.

--debug <boolean> (default = 0): Debug mode - stay in foreground

pmgproxy status

Get daemon status.

pmgproxy stop

Stop the daemon.

DESCRIPTION

This daemon exposes the whole Proxmox Mail Gateway API on TCP port 8006, using HTTPS. It runs as user www-data and has very limited permissions. Operations requiring more permissions are forwarded to the local pmgdaemon.

Requests targeted at other nodes are automatically forwarded to those nodes. This means that you can manage your whole cluster by connecting to a single Proxmox Mail Gateway node.

Alternative HTTPS certificate

By default, pmgproxy uses the certificate /etc/pmg/pmg-api.pem for HTTPS connections. This certificate is self signed, and therefore not trusted by browsers and operating systems by default. You can simply replace this certificate with your own (include the key inside the .pem file) or obtain one from an ACME enabled CA (configurable in the GUI).

Host based Access Control

It is possible to configure “apache2”-like access control lists. Values are read from file /etc/default/pmgproxy. For example:

ALLOW_FROM="10.0.0.1-10.0.0.5,192.168.0.0/22"
DENY_FROM="all"
POLICY="allow"

IP addresses can be specified using any syntax understood by Net::IP. The name all is an alias for 0/0 and ::/0 (meaning all IPv4 and IPv6 addresses).

The default policy is allow.

Match	POLICY=deny	POLICY=allow
Match Allow only	allow	allow
Match Deny only	deny	deny
No match	deny	allow
Match Both Allow & Deny	deny	allow

Match

POLICY=deny

POLICY=allow

Match Allow only

allow

Match Deny only

deny

No match

deny

allow

Match Both Allow & Deny

deny

allow

Listening IP

By default the pmgproxy daemon listens on the wildcard address and accepts connections from both IPv4 and IPv6 clients.

By setting LISTEN_IP in /etc/default/pmgproxy, you can control which IP address the pmgproxy daemon binds to. The IP-address needs to be configured on the system.

Setting the sysctl net.ipv6.bindv6only to the non-default 1 will cause the daemons to only accept connections from IPv6 clients, while usually also causing lots of other issues. If you set this configuration, we recommend either removing the sysctl setting, or setting the LISTEN_IP to 0.0.0.0 (which will allow only IPv4 clients).

LISTEN_IP can be used to restrict the socket to an internal interface, thus leaving less exposure to the public internet, for example:

LISTEN_IP="192.0.2.1"

Similarly, you can also set an IPv6 address:

LISTEN_IP="2001:db8:85a3::1"

Note that if you want to specify a link-local IPv6 address, you need to provide the interface name itself. For example:

LISTEN_IP="fe80::c463:8cff:feb9:6a4e%vmbr0"

The nodes in a cluster need access to pmgproxy for communication, possibly across different subnets. It is not recommended to set LISTEN_IP on clustered systems.

To apply the change you need to either reboot your node or fully restart the pmgproxy service:

systemctl restart pmgproxy.service

Unlike reload, a restart of the pmgproxy service can interrupt some long-running worker processes, for example, a running console. Therefore, you should set a maintenance window to bring this change into effect.

SSL Cipher Suite

You can define the cipher list in /etc/default/pmgproxy, via the CIPHERS (TLS ⇐ 1.2) and CIPHERSUITES (TLS >= 1.3) keys.

For example:

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"

The above is the default. See the ciphers(1) man page from the openssl package for a list of all available options.

The first of these ciphers that is available to both the client and pmgproxy will be used.

Additionally, you can allow the client to choose the cipher from the list above, by disabling the HONOR_CIPHER_ORDER option in /etc/default/pmgproxy:

HONOR_CIPHER_ORDER=0

Supported TLS versions

The insecure SSL versions 2 and 3 are unconditionally disabled for pmgproxy. TLS versions below 1.1 are disabled by default on recent OpenSSL versions, which is honored by pmgproxy (see /etc/ssl/openssl.cnf).

To disable TLS version 1.2, set the following in /etc/default/pmgproxy:

DISABLE_TLS_1_2=1

or, respectively, to disable TLS version 1.3:

DISABLE_TLS_1_3=1

Unless there is a specific reason to do so, it is not recommended to manually adjust the supported TLS versions.

Diffie-Hellman Parameters

You can define the used Diffie-Hellman parameters in /etc/default/pmgproxy by setting DHPARAMS to the path of a file containing DH parameters in PEM format, for example:

DHPARAMS="/path/to/dhparams.pem"

If this option is not set, the built-in skip2048 parameters will be used.

DH parameters are only used if a cipher suite utilizing the DH key exchange algorithm is negotiated.

COMPRESSION

By default pmgproxy uses gzip HTTP-level compression for compressible content, if the client supports it. This can be disabled in /etc/default/pmgproxy

COMPRESSION=0

Copyright and Disclaimer

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/