]>
Commit | Line | Data |
---|---|---|
fa49ddc5 DM |
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. | |
206ef998 | 28 | Operations requiring more permissions are forwarded to the local |
fa49ddc5 DM |
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 | ||
206ef998 SI |
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 | |
cca0f08b SI |
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). | |
fa49ddc5 | 43 | |
e1afb181 SI |
44 | Host based Access Control |
45 | ------------------------- | |
46 | ||
cca0f08b | 47 | It is possible to configure ``apache2''-like access control |
e1afb181 SI |
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 | |
cca0f08b SI |
57 | name `all` is an alias for `0/0` and `::/0` (meaning all IPv4 and IPv6 |
58 | addresses). | |
e1afb181 SI |
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 | ||
cca0f08b SI |
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 to which IP | |
80 | address the `pmgproxy` daemon binds. 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 connection from IPv6 clients, while usually also | |
85 | causing lots of other issues. If you set this configuration we recommend to | |
86 | either remove the `sysctl` setting, or set the `LISTEN_IP` to `0.0.0.0` (which | |
87 | will only allow IPv4 clients). | |
88 | ||
89 | `LISTEN_IP` can be used to only to restricting the socket to an internal | |
90 | interface and thus have 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 on different sub-nets. It is **not recommended** to set `LISTEN_IP` on | |
111 | 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.So, please use a | |
122 | maintenance window to bring this change in effect. | |
123 | ||
124 | ||
e1afb181 SI |
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 | ||
bfdb1534 | 132 | Above is the default. See the `ciphers(1)` man page from the `openssl` |
e1afb181 SI |
133 | package for a list of all available options. |
134 | ||
f5a90440 TL |
135 | The first of these ciphers, available to both the client and the `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`: | |
e1afb181 SI |
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 | |
bfdb1534 | 163 | content if the client supports it. This can be disabled in `/etc/default/pmgproxy` |
e1afb181 SI |
164 | |
165 | COMPRESSION=0 | |
166 | ||
fa49ddc5 DM |
167 | ifdef::manvolnum[] |
168 | include::pmg-copyright.adoc[] | |
169 | endif::manvolnum[] |