9 pveproxy - PVE API Proxy Daemon
15 include::pveproxy.8-synopsis.adoc[]
22 pveproxy - Proxmox VE API Proxy Daemon
23 ======================================
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`.
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
34 [[pveproxy_host_acls]]
35 Host based Access Control
36 -------------------------
38 It is possible to configure ``apache2''-like access control lists. Values are
39 read from file `/etc/default/pveproxy`. For example:
42 ALLOW_FROM="10.0.0.1-10.0.0.5,192.168.0.0/22"
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
51 The default policy is `allow`.
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 |===========================================================
62 [[pveproxy_listening_address]]
66 By default the `pveproxy` and `spiceproxy` daemons listen on the wildcard
67 address and accept connections from both IPv4 and IPv6 clients.
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.
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).
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:
87 Similarly, you can also set an IPv6 address:
90 LISTEN_IP="2001:db8:85a3::1"
93 Note that if you want to specify a link-local IPv6 address, you need to provide
94 the interface name itself. For example:
97 LISTEN_IP="fe80::c463:8cff:feb9:6a4e%vmbr0"
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
104 To apply the change you need to either reboot your node or fully restart the
105 `pveproxy` and `spiceproxy` service:
108 systemctl restart pveproxy.service spiceproxy.service
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
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
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"
126 Above is the default. See the ciphers(1) man page from the openssl
127 package for a list of all available options.
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`):
136 Supported TLS versions
137 ----------------------
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`).
143 To disable TLS version 1.2 or 1.3, set the following in `/etc/default/pveproxy`:
151 NOTE: Unless there is a specific reason to do so, it is not recommended to
152 manually adjust the supported TLS versions.
155 Diffie-Hellman Parameters
156 -------------------------
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
162 DHPARAMS="/path/to/dhparams.pem"
164 If this option is not set, the built-in `skip2048` parameters will be
167 NOTE: DH parameters are only used if a cipher suite utilizing the DH key
168 exchange algorithm is negotiated.
170 [[pveproxy_custom_tls_cert]]
171 Alternative HTTPS certificate
172 -----------------------------
174 You can change the certificate used to an external one or to one obtained via
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.
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:
186 TLS_KEY_FILE="/secrets/pveproxy.key"
188 NOTE: The included ACME integration does not honor this setting.
190 See the Host System Administration chapter of the documentation for details.
192 [[pveproxy_response_compression]]
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`
202 include::pve-copyright.adoc[]