Drop note for before-queue filtering

[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 for 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 (please include the key inside the '.pem' file).


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`.

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


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"

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, available to both the client and the `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[]