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