pveproxy: update documentation on 'all' alias

[pve-docs.git] / pveproxy.adoc

ifdef::manvolnum[]
pveproxy(8)
===========
:pve-toplevel:

NAME
----

pveproxy - PVE API Proxy Daemon


SYNOPSIS
--------

include::pveproxy.8-synopsis.adoc[]

DESCRIPTION
-----------
endif::manvolnum[]

ifndef::manvolnum[]
pveproxy - Proxmox VE API Proxy Daemon
======================================
endif::manvolnum[]

This daemon exposes the whole {pve} API on TCP port 8006 using
HTTPS. It runs as user `www-data` and has very limited permissions.
Operation requiring more permissions are forwarded to the local
`pvedaemon`.

Requests targeted for other nodes are automatically forwarded to those
nodes. This means that you can manage your whole cluster by connecting
to a single {pve} node.

Host based Access Control
-------------------------

It is possible to configure ``apache2''-like access control
lists. Values are read from file `/etc/default/pveproxy`. For example:

----
ALLOW_FROM="10.0.0.1-10.0.0.5,192.168.0.0/22"
DENY_FROM="all"
POLICY="allow"
----

IP addresses can be specified using any syntax understood by `Net::IP`. The
name `all` is an alias for `0/0` and `::/0` (meaning all IPv4 and IPv6
addresses).

The default policy is `allow`.

[width="100%",options="header"]
|===========================================================
| Match                      | POLICY=deny | POLICY=allow
| Match Allow only           | allow       | allow
| Match Deny only            | deny        | deny
| No match                   | deny        | allow
| Match Both Allow & Deny    | deny        | allow
|===========================================================


Listening IP
------------

By default the `pveproxy` and `spiceproxy` daemons listen on the wildcard
address and accept connections from both IPv4 and IPv6 clients.

By setting `LISTEN_IP` in `/etc/default/pveproxy` you can control to which IP
address the `pveproxy` and `spiceproxy` daemons bind. The IP-address needs to
be configured on the system.

This can be used to listen only to an internal interface and thus have less
exposure to the public internet:

----
LISTEN_IP="192.0.2.1"
----

Similarly, you can also set an IPv6 address:

----
LISTEN_IP="2001:db8:85a3::1"
----

Note that if you want to specify a link-local IPv6 address, you need to provide
the interface name itself. For example:

----
LISTEN_IP="fe80::c463:8cff:feb9:6a4e%vmbr0"
----

WARNING: The nodes in a cluster need access to `pveproxy` for communication,
possibly on different sub-nets. It is **not recommended** to set `LISTEN_IP` on
clustered systems.

To apply the change you need to either reboot your node or fully restart the
`pveproxy` and `spiceproxy` service:

----
systemctl restart pveproxy.service spiceproxy.service
----

NOTE: Unlike `reload`, a `restart` of the pveproxy service can interrupt some
long-running worker processes, for example a running console or shell from a
virtual guest. So, please use a maintenance window to bring this change in
effect.

NOTE: setting the `sysctl` `net.ipv6.bindv6only` to `1` will cause the daemons
  to only accept connection from IPv6 clients. This non-default setting usually
  also causes other issues. Either remove the `sysctl` setting, or set the
  `LISTEN_IP` to `0.0.0.0` (which will only allow IPv4 clients).


SSL Cipher Suite
----------------

You can define the cipher list in `/etc/default/pveproxy`, for example

 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"

Above is the default. See the ciphers(1) man page from the openssl
package for a list of all available options.

Additionally, you can set the client to choose the cipher used in
`/etc/default/pveproxy` (default is the first cipher in the list available to
both client and `pveproxy`):

 HONOR_CIPHER_ORDER=0


Diffie-Hellman Parameters
-------------------------

You can define the used Diffie-Hellman parameters in
`/etc/default/pveproxy` by setting `DHPARAMS` to the path of a file
containing DH parameters in PEM format, for example

 DHPARAMS="/path/to/dhparams.pem"

If this option is not set, the built-in `skip2048` parameters will be
used.

NOTE: DH parameters are only used if a cipher suite utilizing the DH key
exchange algorithm is negotiated.

Alternative HTTPS certificate
-----------------------------

You can change the certificate used to an external one or to one obtained via
ACME.

pveproxy uses `/etc/pve/local/pveproxy-ssl.pem` and
`/etc/pve/local/pveproxy-ssl.key`, if present, and falls back to
`/etc/pve/local/pve-ssl.pem` and `/etc/pve/local/pve-ssl.key`.
The private key may not use a passphrase.

See the Host System Administration chapter of the documentation for details.

COMPRESSION
-----------

By default `pveproxy` uses gzip HTTP-level compression for compressible
content, if the client supports it. This can disabled in `/etc/default/pveproxy`

 COMPRESSION=0

ifdef::manvolnum[]
include::pve-copyright.adoc[]
endif::manvolnum[]