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
  27 HTTPS. It runs as user `www-data` and has very limited permissions.
  28 Operation requiring more permissions are forwarded to the local
  29 `pvedaemon`.
  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 {pve} node.
  34
  35 Host based Access Control
  36 -------------------------
  37
  38 It is possible to configure ``apache2''-like access control
  39 lists. Values are 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
  63 Listening IP
  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`, for example
 121
 122  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"
 123
 124 Above is the default. See the ciphers(1) man page from the openssl
 125 package for a list of all available options.
 126
 127 Additionally, you can set the client to choose the cipher used in
 128 `/etc/default/pveproxy` (default is the first cipher in the list available to
 129 both client and `pveproxy`):
 130
 131  HONOR_CIPHER_ORDER=0
 132
 133
 134 Diffie-Hellman Parameters
 135 -------------------------
 136
 137 You can define the used Diffie-Hellman parameters in
 138 `/etc/default/pveproxy` by setting `DHPARAMS` to the path of a file
 139 containing DH parameters in PEM format, for example
 140
 141  DHPARAMS="/path/to/dhparams.pem"
 142
 143 If this option is not set, the built-in `skip2048` parameters will be
 144 used.
 145
 146 NOTE: DH parameters are only used if a cipher suite utilizing the DH key
 147 exchange algorithm is negotiated.
 148
 149 Alternative HTTPS certificate
 150 -----------------------------
 151
 152 You can change the certificate used to an external one or to one obtained via
 153 ACME.
 154
 155 pveproxy uses `/etc/pve/local/pveproxy-ssl.pem` and
 156 `/etc/pve/local/pveproxy-ssl.key`, if present, and falls back to
 157 `/etc/pve/local/pve-ssl.pem` and `/etc/pve/local/pve-ssl.key`.
 158 The private key may not use a passphrase.
 159
 160 See the Host System Administration chapter of the documentation for details.
 161
 162 COMPRESSION
 163 -----------
 164
 165 By default `pveproxy` uses gzip HTTP-level compression for compressible
 166 content, if the client supports it. This can disabled in `/etc/default/pveproxy`
 167
 168  COMPRESSION=0
 169
 170 ifdef::manvolnum[]
 171 include::pve-copyright.adoc[]
 172 endif::manvolnum[]