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