apitoken: use CAUTION for token-only-once-visible note

[pve-docs.git] / certificate-management.adoc

[[sysadmin_certificate_management]]
Certificate Management
----------------------
ifdef::wiki[]
:pve-toplevel:
endif::wiki[]


Certificates for communication within the cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Each {PVE} cluster creates its own (self-signed) Certificate Authority (CA) and
generates a certificate for each node which gets signed by the aforementioned
CA. These certificates are used for encrypted communication with the cluster's
`pveproxy` service and the Shell/Console feature if SPICE is used.

The CA certificate and key are stored in the xref:chapter_pmxcfs[Proxmox Cluster File System (pmxcfs)].

Certificates for API and web GUI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The REST API and web GUI are provided by the `pveproxy` service, which runs on
each node.

You have the following options for the certificate used by `pveproxy`:

1. By default the node-specific certificate in
`/etc/pve/nodes/NODENAME/pve-ssl.pem` is used. This certificate is signed by
the cluster CA and therefore not trusted by browsers and operating systems by
default.
2. use an externally provided certificate (e.g. signed by a commercial CA).
3. use ACME (e.g., Let's Encrypt) to get a trusted certificate with automatic
renewal, this is also integrated in the {pve} API and Webinterface.

For options 2 and 3 the file `/etc/pve/local/pveproxy-ssl.pem` (and
`/etc/pve/local/pveproxy-ssl.key`, which needs to be without password) is used.

NOTE: Keep in mind that `/etc/pve/local` is a node specific symlink to
`/etc/pve/nodes/NODENAME`.

Certificates are managed with the {PVE} Node management command
(see the `pvenode(1)` manpage).

WARNING: Do not replace or manually modify the automatically generated node
certificate files in `/etc/pve/local/pve-ssl.pem` and
`/etc/pve/local/pve-ssl.key` or the cluster CA files in
`/etc/pve/pve-root-ca.pem` and `/etc/pve/priv/pve-root-ca.key`.

Getting trusted certificates via ACME
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
{PVE} includes an implementation of the **A**utomatic **C**ertificate
**M**anagement **E**nvironment **ACME** protocol, allowing {pve} admins to
interface with Let's Encrypt for easy setup of trusted TLS certificates which
are accepted out of the box on most modern operating systems and browsers.

Currently the two ACME endpoints implemented are Let's Encrypt (LE) and its
staging environment (see https://letsencrypt.org), both using the standalone
HTTP challenge.

Because of https://letsencrypt.org/docs/rate-limits/[rate-limits] you should use
LE `staging` for experiments.

There are a few prerequisites to use Let's Encrypt:

1. **Port 80** of the node needs to be reachable from the internet.
2. There **must** be no other listener on port 80.
3. The requested (sub)domain needs to resolve to a public IP of the Node.
4. You have to accept the ToS of Let's Encrypt.

At the moment the GUI uses only the default ACME account.

.Example: Sample `pvenode` invocation for using Let's Encrypt certificates

----
root@proxmox:~# pvenode acme account register default mail@example.invalid
Directory endpoints:
0) Let's Encrypt V2 (https://acme-v02.api.letsencrypt.org/directory)
1) Let's Encrypt V2 Staging (https://acme-staging-v02.api.letsencrypt.org/directory)
2) Custom
Enter selection:
1

Attempting to fetch Terms of Service from 'https://acme-staging-v02.api.letsencrypt.org/directory'..
Terms of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
Do you agree to the above terms? [y|N]y

Attempting to register account with 'https://acme-staging-v02.api.letsencrypt.org/directory'..
Generating ACME account key..
Registering ACME account..
Registration successful, account URL: 'https://acme-staging-v02.api.letsencrypt.org/acme/acct/xxxxxxx'
Task OK
root@proxmox:~# pvenode acme account list
default
root@proxmox:~# pvenode config set --acme domains=example.invalid
root@proxmox:~# pvenode acme cert order
Loading ACME account details
Placing ACME order
Order URL: https://acme-staging-v02.api.letsencrypt.org/acme/order/xxxxxxxxxxxxxx

Getting authorization details from
'https://acme-staging-v02.api.letsencrypt.org/acme/authz/xxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxx-xxxxxxx'
... pending!
Setting up webserver
Triggering validation
Sleeping for 5 seconds
Status is 'valid'!

All domains validated!

Creating CSR
Finalizing order
Checking order status
valid!

Downloading certificate
Setting pveproxy certificate and key
Restarting pveproxy
Task OK
----

Switching from the `staging` to the regular ACME directory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Changing the ACME directory for an account is unsupported. If you want to switch
an account from the `staging` ACME directory to the regular, trusted, one you
need to deactivate it and recreate it.

This procedure is also needed to change the default ACME account used in the GUI.

.Example: Changing the `default` ACME account from the `staging` to the regular directory

----
root@proxmox:~# pvenode acme account info default
Directory URL: https://acme-staging-v02.api.letsencrypt.org/directory
Account URL: https://acme-staging-v02.api.letsencrypt.org/acme/acct/6332194
Terms Of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf

Account information:
ID: xxxxxxx
Contact:
        - mailto:example@proxmox.com
Creation date: 2018-07-31T08:41:44.54196435Z
Initial IP: 192.0.2.1
Status: valid

root@proxmox:~# pvenode acme account deactivate default
Renaming account file from '/etc/pve/priv/acme/default' to '/etc/pve/priv/acme/_deactivated_default_4'
Task OK

root@proxmox:~# pvenode acme account register default example@proxmox.com
Directory endpoints:
0) Let's Encrypt V2 (https://acme-v02.api.letsencrypt.org/directory)
1) Let's Encrypt V2 Staging (https://acme-staging-v02.api.letsencrypt.org/directory)
2) Custom
Enter selection:
0

Attempting to fetch Terms of Service from 'https://acme-v02.api.letsencrypt.org/directory'..
Terms of Service: https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
Do you agree to the above terms? [y|N]y

Attempting to register account with 'https://acme-v02.api.letsencrypt.org/directory'..
Generating ACME account key..
Registering ACME account..
Registration successful, account URL: 'https://acme-v02.api.letsencrypt.org/acme/acct/39335247'
Task OK
----

Automatic renewal of ACME certificates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If a node has been successfully configured with an ACME-provided certificate
(either via pvenode or via the GUI), the certificate will be automatically
renewed by the pve-daily-update.service. Currently, renewal will be attempted
if the certificate has expired already, or will expire in the next 30 days.