tfa: rework note regarding cluster join and tfa

[pmg-docs.git] / pmgproxy.adoc

ifdef::manvolnum[]
pmgproxy(8)
===========
:pmg-toplevel:

NAME
----

pmgproxy - Proxmox Mail Gateway API Proxy Daemon


SYNOPSIS
--------

include::pmgproxy.8-synopsis.adoc[]

DESCRIPTION
-----------
endif::manvolnum[]

ifndef::manvolnum[]
pmgproxy - Proxmox Mail Gateway API Proxy Daemon
================================================
endif::manvolnum[]

This daemon exposes the whole {pmg} 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 {pmg} 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`.

[width="100%",options="header"]
|===========================================================
| 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
|===========================================================


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"
----

WARNING: 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
----

NOTE: 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`, 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


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.

NOTE: 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

ifdef::manvolnum[]
include::pmg-copyright.adoc[]
endif::manvolnum[]