pmgproxy.adoc

   1 ifdef::manvolnum[]
   2 pmgproxy(8)
   3 ===========
   4 :pmg-toplevel:
   5
   6 NAME
   7 ----
   8
   9 pmgproxy - Proxmox Mail Gateway API Proxy Daemon
  10
  11
  12 SYNOPSIS
  13 --------
  14
  15 include::pmgproxy.8-synopsis.adoc[]
  16
  17 DESCRIPTION
  18 -----------
  19 endif::manvolnum[]
  20
  21 ifndef::manvolnum[]
  22 pmgproxy - Proxmox Mail Gateway API Proxy Daemon
  23 ================================================
  24 endif::manvolnum[]
  25
  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
  29 `pmgdaemon`.
  30
  31 Requests targeted at 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.
  34
  35 Alternative HTTPS certificate
  36 -----------------------------
  37
  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).
  43
  44 Host based Access Control
  45 -------------------------
  46
  47 It is possible to configure ``apache2''-like access control
  48 lists. Values are read from file `/etc/default/pmgproxy`. For example:
  49
  50 ----
  51 ALLOW_FROM="10.0.0.1-10.0.0.5,192.168.0.0/22"
  52 DENY_FROM="all"
  53 POLICY="allow"
  54 ----
  55
  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
  58 addresses).
  59
  60 The default policy is `allow`.
  61
  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 |===========================================================
  70
  71
  72 Listening IP
  73 ------------
  74
  75 By default the `pmgproxy` daemon listens on the wildcard address and accepts
  76 connections from both IPv4 and IPv6 clients.
  77
  78
  79 By setting `LISTEN_IP` in `/etc/default/pmgproxy`, you can control which IP
  80 address the `pmgproxy` daemon binds to. The IP-address needs to be configured on
  81 the system.
  82
  83 Setting the `sysctl` `net.ipv6.bindv6only` to the non-default `1` will cause
  84 the daemons to only accept connections from IPv6 clients, while usually also
  85 causing lots of other issues. If you set this configuration, we recommend either
  86 removing the `sysctl` setting, or setting the `LISTEN_IP` to `0.0.0.0` (which
  87 will allow only IPv4 clients).
  88
  89 `LISTEN_IP` can be used to restrict the socket to an internal
  90 interface, thus leaving less exposure to the public internet, for example:
  91
  92 ----
  93 LISTEN_IP="192.0.2.1"
  94 ----
  95
  96 Similarly, you can also set an IPv6 address:
  97
  98 ----
  99 LISTEN_IP="2001:db8:85a3::1"
 100 ----
 101
 102 Note that if you want to specify a link-local IPv6 address, you need to provide
 103 the interface name itself. For example:
 104
 105 ----
 106 LISTEN_IP="fe80::c463:8cff:feb9:6a4e%vmbr0"
 107 ----
 108
 109 WARNING: The nodes in a cluster need access to `pmgproxy` for communication,
 110 possibly across different subnets. It is **not recommended** to set `LISTEN_IP`
 111 on clustered systems.
 112
 113 To apply the change you need to either reboot your node or fully restart the
 114 `pmgproxy` service:
 115
 116 ----
 117 systemctl restart pmgproxy.service
 118 ----
 119
 120 NOTE: Unlike `reload`, a `restart` of the pmgproxy service can interrupt some
 121 long-running worker processes, for example, a running console. Therefore, you
 122 should set a maintenance window to bring this change into effect.
 123
 124
 125 SSL Cipher Suite
 126 ----------------
 127
 128 You can define the cipher list in `/etc/default/pmgproxy`, for example:
 129
 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"
 131
 132 The above is the default. See the `ciphers(1)` man page from the `openssl`
 133 package for a list of all available options.
 134
 135 The first of these ciphers that is available to both the client and `pmgproxy`
 136 will be used.
 137
 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`:
 140
 141  HONOR_CIPHER_ORDER=0
 142
 143
 144 Diffie-Hellman Parameters
 145 -------------------------
 146
 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:
 150
 151  DHPARAMS="/path/to/dhparams.pem"
 152
 153 If this option is not set, the built-in `skip2048` parameters will be
 154 used.
 155
 156 NOTE: DH parameters are only used if a cipher suite utilizing the DH key
 157 exchange algorithm is negotiated.
 158
 159 COMPRESSION
 160 -----------
 161
 162 By default `pmgproxy` uses gzip HTTP-level compression for compressible
 163 content, if the client supports it. This can be disabled in
 164 `/etc/default/pmgproxy`
 165
 166  COMPRESSION=0
 167
 168 ifdef::manvolnum[]
 169 include::pmg-copyright.adoc[]
 170 endif::manvolnum[]