pveproxy.adoc

   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[]