]>
Commit | Line | Data |
---|---|---|
1 | ifdef::manvolnum[] | |
2 | pveproxy(8) | |
3 | =========== | |
4 | :pve-toplevel: | |
5 | ||
6 | NAME | |
7 | ---- | |
8 | ||
9 | pveproxy - PVE API Proxy Daemon | |
10 | ||
11 | ||
12 | SYNOPSIS | |
13 | -------- | |
14 | ||
15 | include::pveproxy.8-synopsis.adoc[] | |
16 | ||
17 | DESCRIPTION | |
18 | ----------- | |
19 | endif::manvolnum[] | |
20 | ||
21 | ifndef::manvolnum[] | |
22 | pveproxy - Proxmox VE API Proxy Daemon | |
23 | ====================================== | |
24 | endif::manvolnum[] | |
25 | ||
26 | This daemon exposes the whole {pve} API on TCP port 8006 using HTTPS. It runs | |
27 | as user `www-data` and has very limited permissions. Operation requiring more | |
28 | permissions are forwarded to the local `pvedaemon`. | |
29 | ||
30 | Requests targeted for other nodes are automatically forwarded to those nodes. | |
31 | This means that you can manage your whole cluster by connecting to a single | |
32 | {pve} node. | |
33 | ||
34 | [[pveproxy_host_acls]] | |
35 | Host based Access Control | |
36 | ------------------------- | |
37 | ||
38 | It is possible to configure ``apache2''-like access control lists. Values are | |
39 | read from file `/etc/default/pveproxy`. For example: | |
40 | ||
41 | ---- | |
42 | ALLOW_FROM="10.0.0.1-10.0.0.5,192.168.0.0/22" | |
43 | DENY_FROM="all" | |
44 | POLICY="allow" | |
45 | ---- | |
46 | ||
47 | IP addresses can be specified using any syntax understood by `Net::IP`. The | |
48 | name `all` is an alias for `0/0` and `::/0` (meaning all IPv4 and IPv6 | |
49 | addresses). | |
50 | ||
51 | The default policy is `allow`. | |
52 | ||
53 | [width="100%",options="header"] | |
54 | |=========================================================== | |
55 | | Match | POLICY=deny | POLICY=allow | |
56 | | Match Allow only | allow | allow | |
57 | | Match Deny only | deny | deny | |
58 | | No match | deny | allow | |
59 | | Match Both Allow & Deny | deny | allow | |
60 | |=========================================================== | |
61 | ||
62 | [[pveproxy_listening_address]] | |
63 | Listening IP Address | |
64 | -------------------- | |
65 | ||
66 | By default the `pveproxy` and `spiceproxy` daemons listen on the wildcard | |
67 | address and accept connections from both IPv4 and IPv6 clients. | |
68 | ||
69 | ||
70 | By setting `LISTEN_IP` in `/etc/default/pveproxy` you can control to which IP | |
71 | address the `pveproxy` and `spiceproxy` daemons bind. The IP-address needs to | |
72 | be configured on the system. | |
73 | ||
74 | Setting the `sysctl` `net.ipv6.bindv6only` to the non-default `1` will cause | |
75 | the daemons to only accept connection from IPv6 clients, while usually also | |
76 | causing lots of other issues. If you set this configuration we recommend to | |
77 | either remove the `sysctl` setting, or set the `LISTEN_IP` to `0.0.0.0` (which | |
78 | will only allow IPv4 clients). | |
79 | ||
80 | `LISTEN_IP` can be used to only to restricting the socket to an internal | |
81 | interface and thus have less exposure to the public internet, for example: | |
82 | ||
83 | ---- | |
84 | LISTEN_IP="192.0.2.1" | |
85 | ---- | |
86 | ||
87 | Similarly, you can also set an IPv6 address: | |
88 | ||
89 | ---- | |
90 | LISTEN_IP="2001:db8:85a3::1" | |
91 | ---- | |
92 | ||
93 | Note that if you want to specify a link-local IPv6 address, you need to provide | |
94 | the interface name itself. For example: | |
95 | ||
96 | ---- | |
97 | LISTEN_IP="fe80::c463:8cff:feb9:6a4e%vmbr0" | |
98 | ---- | |
99 | ||
100 | WARNING: The nodes in a cluster need access to `pveproxy` for communication, | |
101 | possibly on different sub-nets. It is **not recommended** to set `LISTEN_IP` on | |
102 | clustered systems. | |
103 | ||
104 | To apply the change you need to either reboot your node or fully restart the | |
105 | `pveproxy` and `spiceproxy` service: | |
106 | ||
107 | ---- | |
108 | systemctl restart pveproxy.service spiceproxy.service | |
109 | ---- | |
110 | ||
111 | NOTE: Unlike `reload`, a `restart` of the pveproxy service can interrupt some | |
112 | long-running worker processes, for example a running console or shell from a | |
113 | virtual guest. So, please use a maintenance window to bring this change in | |
114 | effect. | |
115 | ||
116 | ||
117 | SSL Cipher Suite | |
118 | ---------------- | |
119 | ||
120 | You can define the cipher list in `/etc/default/pveproxy` via the `CIPHERS` | |
121 | (TLS <= 1.2) and `CIPHERSUITES` (TLS >= 1.3) keys. For example | |
122 | ||
123 | 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" | |
124 | CIPHERSUITES="TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256" | |
125 | ||
126 | Above is the default. See the ciphers(1) man page from the openssl | |
127 | package for a list of all available options. | |
128 | ||
129 | Additionally, you can set the client to choose the cipher used in | |
130 | `/etc/default/pveproxy` (default is the first cipher in the list available to | |
131 | both client and `pveproxy`): | |
132 | ||
133 | HONOR_CIPHER_ORDER=0 | |
134 | ||
135 | ||
136 | Supported TLS versions | |
137 | ---------------------- | |
138 | ||
139 | The insecure SSL versions 2 and 3 are unconditionally disabled for pveproxy. | |
140 | TLS versions below 1.1 are disabled by default on recent OpenSSL versions, | |
141 | which is honored by `pveproxy` (see `/etc/ssl/openssl.cnf`). | |
142 | ||
143 | To disable TLS version 1.2 or 1.3, set the following in `/etc/default/pveproxy`: | |
144 | ||
145 | DISABLE_TLS_1_2=1 | |
146 | ||
147 | or, respectively: | |
148 | ||
149 | DISABLE_TLS_1_3=1 | |
150 | ||
151 | NOTE: Unless there is a specific reason to do so, it is not recommended to | |
152 | manually adjust the supported TLS versions. | |
153 | ||
154 | ||
155 | Diffie-Hellman Parameters | |
156 | ------------------------- | |
157 | ||
158 | You can define the used Diffie-Hellman parameters in | |
159 | `/etc/default/pveproxy` by setting `DHPARAMS` to the path of a file | |
160 | containing DH parameters in PEM format, for example | |
161 | ||
162 | DHPARAMS="/path/to/dhparams.pem" | |
163 | ||
164 | If this option is not set, the built-in `skip2048` parameters will be | |
165 | used. | |
166 | ||
167 | NOTE: DH parameters are only used if a cipher suite utilizing the DH key | |
168 | exchange algorithm is negotiated. | |
169 | ||
170 | [[pveproxy_custom_tls_cert]] | |
171 | Alternative HTTPS certificate | |
172 | ----------------------------- | |
173 | ||
174 | You can change the certificate used to an external one or to one obtained via | |
175 | ACME. | |
176 | ||
177 | pveproxy uses `/etc/pve/local/pveproxy-ssl.pem` and | |
178 | `/etc/pve/local/pveproxy-ssl.key`, if present, and falls back to | |
179 | `/etc/pve/local/pve-ssl.pem` and `/etc/pve/local/pve-ssl.key`. | |
180 | The private key may not use a passphrase. | |
181 | ||
182 | It is possible to override the location of the certificate private key | |
183 | `/etc/pve/local/pveproxy-ssl.key` by setting `TLS_KEY_FILE` in | |
184 | `/etc/default/pveproxy`, for example: | |
185 | ||
186 | TLS_KEY_FILE="/secrets/pveproxy.key" | |
187 | ||
188 | NOTE: The included ACME integration does not honor this setting. | |
189 | ||
190 | See the Host System Administration chapter of the documentation for details. | |
191 | ||
192 | [[pveproxy_response_compression]] | |
193 | Response Compression | |
194 | -------------------- | |
195 | ||
196 | By default `pveproxy` uses gzip HTTP-level compression for compressible | |
197 | content, if the client supports it. This can disabled in `/etc/default/pveproxy` | |
198 | ||
199 | COMPRESSION=0 | |
200 | ||
201 | ifdef::manvolnum[] | |
202 | include::pve-copyright.adoc[] | |
203 | endif::manvolnum[] |