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 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.
  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 (please include the key inside the '.pem' file).
  42
  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`.
  58
  59 The default policy is `allow`.
  60
  61 [width="100%",options="header"]
  62 |===========================================================
  63 | Match                      | POLICY=deny | POLICY=allow
  64 | Match Allow only           | allow       | allow
  65 | Match Deny only            | deny        | deny
  66 | No match                   | deny        | allow
  67 | Match Both Allow & Deny    | deny        | allow
  68 |===========================================================
  69
  70
  71 SSL Cipher Suite
  72 ----------------
  73
  74 You can define the cipher list in `/etc/default/pmgproxy`, for example
  75
  76  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"
  77
  78 Above is the default. See the `ciphers(1)` man page from the `openssl`
  79 package for a list of all available options.
  80
  81 The first of these ciphers, available to both the client and the `pmgproxy`,
  82 will be used.
  83
  84 Additionally you can allow the client to choose the cipher from the list above
  85 by disabling the HONOR_CIPHER_ORDER option in `/etc/default/pmgproxy`:
  86
  87  HONOR_CIPHER_ORDER=0
  88
  89
  90 Diffie-Hellman Parameters
  91 -------------------------
  92
  93 You can define the used Diffie-Hellman parameters in
  94 `/etc/default/pmgproxy` by setting `DHPARAMS` to the path of a file
  95 containing DH parameters in PEM format, for example
  96
  97  DHPARAMS="/path/to/dhparams.pem"
  98
  99 If this option is not set, the built-in `skip2048` parameters will be
 100 used.
 101
 102 NOTE: DH parameters are only used if a cipher suite utilizing the DH key
 103 exchange algorithm is negotiated.
 104
 105 COMPRESSION
 106 -----------
 107
 108 By default `pmgproxy` uses gzip HTTP-level compression for compressible
 109 content if the client supports it. This can be disabled in `/etc/default/pmgproxy`
 110
 111  COMPRESSION=0
 112
 113 ifdef::manvolnum[]
 114 include::pmg-copyright.adoc[]
 115 endif::manvolnum[]