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 By setting `LISTEN_IP` in `/etc/default/pveproxy` you can control to which IP
  70 address the `pveproxy` and `spiceproxy` daemons bind. The IP-address needs to
  71 be configured on the system.
  72
  73 This can be used to listen only to an internal interface and thus have less
  74 exposure to the public internet:
  75
  76 ----
  77 LISTEN_IP="192.0.2.1"
  78 ----
  79
  80 Similarly, you can also set an IPv6 address:
  81
  82 ----
  83 LISTEN_IP="2001:db8:85a3::1"
  84 ----
  85
  86 Note that if you want to specify a link-local IPv6 address, you need to provide
  87 the interface name itself. For example:
  88
  89 ----
  90 LISTEN_IP="fe80::c463:8cff:feb9:6a4e%vmbr0"
  91 ----
  92
  93 WARNING: The nodes in a cluster need access to `pveproxy` for communication,
  94 possibly on different sub-nets. It is **not recommended** to set `LISTEN_IP` on
  95 clustered systems.
  96
  97 To apply the change you need to either reboot your node or fully restart the
  98 `pveproxy` and `spiceproxy` service:
  99
 100 ----
 101 systemctl restart pveproxy.service spiceproxy.service
 102 ----
 103
 104 NOTE: Unlike `reload`, a `restart` of the pveproxy service can interrupt some
 105 long-running worker processes, for example a running console or shell from a
 106 virtual guest. So, please use a maintenance window to bring this change in
 107 effect.
 108
 109 NOTE: setting the `sysctl` `net.ipv6.bindv6only` to `1` will cause the daemons
 110   to only accept connection from IPv6 clients. This non-default setting usually
 111   also causes other issues. Either remove the `sysctl` setting, or set the
 112   `LISTEN_IP` to `0.0.0.0` (which will only allow IPv4 clients).
 113
 114
 115 SSL Cipher Suite
 116 ----------------
 117
 118 You can define the cipher list in `/etc/default/pveproxy`, for example
 119
 120  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"
 121
 122 Above is the default. See the ciphers(1) man page from the openssl
 123 package for a list of all available options.
 124
 125 Additionally, you can set the client to choose the cipher used in
 126 `/etc/default/pveproxy` (default is the first cipher in the list available to
 127 both client and `pveproxy`):
 128
 129  HONOR_CIPHER_ORDER=0
 130
 131
 132 Diffie-Hellman Parameters
 133 -------------------------
 134
 135 You can define the used Diffie-Hellman parameters in
 136 `/etc/default/pveproxy` by setting `DHPARAMS` to the path of a file
 137 containing DH parameters in PEM format, for example
 138
 139  DHPARAMS="/path/to/dhparams.pem"
 140
 141 If this option is not set, the built-in `skip2048` parameters will be
 142 used.
 143
 144 NOTE: DH parameters are only used if a cipher suite utilizing the DH key
 145 exchange algorithm is negotiated.
 146
 147 Alternative HTTPS certificate
 148 -----------------------------
 149
 150 You can change the certificate used to an external one or to one obtained via
 151 ACME.
 152
 153 pveproxy uses `/etc/pve/local/pveproxy-ssl.pem` and
 154 `/etc/pve/local/pveproxy-ssl.key`, if present, and falls back to
 155 `/etc/pve/local/pve-ssl.pem` and `/etc/pve/local/pve-ssl.key`.
 156 The private key may not use a passphrase.
 157
 158 See the Host System Administration chapter of the documentation for details.
 159
 160 COMPRESSION
 161 -----------
 162
 163 By default `pveproxy` uses gzip HTTP-level compression for compressible
 164 content, if the client supports it. This can disabled in `/etc/default/pveproxy`
 165
 166  COMPRESSION=0
 167
 168 ifdef::manvolnum[]
 169 include::pve-copyright.adoc[]
 170 endif::manvolnum[]