]>
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 | ||
571cbbdf | 26 | This daemon exposes the whole {pmg} API on TCP port 8006, using |
fa49ddc5 | 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 | ||
571cbbdf | 31 | Requests targeted at other nodes are automatically forwarded to those |
fa49ddc5 DM |
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 | ||
571cbbdf DW |
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 | |
cca0f08b SI |
81 | the system. |
82 | ||
83 | Setting the `sysctl` `net.ipv6.bindv6only` to the non-default `1` will cause | |
571cbbdf DW |
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). | |
cca0f08b | 88 | |
571cbbdf DW |
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: | |
cca0f08b SI |
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, | |
571cbbdf DW |
110 | possibly across different subnets. It is **not recommended** to set `LISTEN_IP` |
111 | on clustered systems. | |
cca0f08b SI |
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 | |
571cbbdf DW |
121 | long-running worker processes, for example, a running console. Therefore, you |
122 | should set a maintenance window to bring this change into effect. | |
cca0f08b SI |
123 | |
124 | ||
e1afb181 SI |
125 | SSL Cipher Suite |
126 | ---------------- | |
127 | ||
571cbbdf | 128 | You can define the cipher list in `/etc/default/pmgproxy`, for example: |
e1afb181 SI |
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 | ||
571cbbdf | 132 | The 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 | ||
571cbbdf | 135 | The first of these ciphers that is available to both the client and `pmgproxy` |
f5a90440 TL |
136 | will be used. |
137 | ||
571cbbdf | 138 | Additionally, you can allow the client to choose the cipher from the list above, |
f5a90440 | 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 | |
571cbbdf | 149 | containing DH parameters in PEM format, for example: |
e1afb181 SI |
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 | |
571cbbdf DW |
163 | content, if the client supports it. This can be disabled in |
164 | `/etc/default/pmgproxy` | |
e1afb181 SI |
165 | |
166 | COMPRESSION=0 | |
167 | ||
fa49ddc5 DM |
168 | ifdef::manvolnum[] |
169 | include::pmg-copyright.adoc[] | |
170 | endif::manvolnum[] |