HTTPS Certificate Configuration

From Proxmox Backup Server
Jump to navigation Jump to search

Introduction

This is a how-to for changing the web server certificate used by Proxmox Backup Server, in order to enable the usage of publicly trusted certificates issued by a CA of your choice (like Let's Encrypt or a commercial CA).

Important Note

Creating a new certificate requires changes the fingerprint a client will see when connecting to the server. You need to update it for all clients, else they will refuse connecting to the server!

With a trusted certificate clients do not require a fingerprint to verify the server, if your certificate is trusted you should drop the fingerprint from all client configurations to avoid updating it.

Certificate and Key File

The certificate and key, which are used for the TLS encryption by proxmox-backup-proxy are:

  • /etc/proxmox-backup/proxy.pem (certificate)
The pem file contains the certificate, potentially including one or more intermediate certificates
  • /etc/proxmox-backup/proxy.key (key)
The key file contains the private key used for the certificate.

File Owner and Permissions

Both files need to be owned by the root user and the backup group and should not be readable by others (mode o640):

chown root:backup /etc/proxmox-backup/proxy.pem /etc/proxmox-backup/proxy.key
chmod 640 /etc/proxmox-backup/proxy.pem /etc/proxmox-backup/proxy.key

Activating Certificate Change

Once the certificate and key files are changed you need to reload (avoid restart, they interrupt running (backup) jobs) the proxy daemon:

systemctl reload proxmox-backup-proxy

Revert to Default Configuration

You can always recreate a fresh self-signed certificate and start fresh by running:

proxmox-backup-manager cert update --force
systemctl reload proxmox-backup-proxy

WARNING: Creating a new certificate requires you to update the fingerprint for all clients, else they will refuse connecting to the server!

Let's Encrypt using acme.sh

Until Proxmox Backup Server handles issuing certificates from Let's Encrypt itself you can configure getting and refreshing certificates with external tools.

This how-to shows how to get a publicly trusted certificate from Let's Encrypt using acme.sh

The how-to only provides minimal instructions - read up on other options, which might be more fitting in your environment, for example, using the DNS challenge.

Download and Installation

You can obtain acme.sh directly from GitHub and install it to root account:

git clone https://github.com/acmesh-official/acme.sh.git
cd acme.sh && ./acme.sh --install --accountemail <your-email>

Issuing and Configuration

To write the files to the appropriate location, with fitting owner and mode for domain.example

acme.sh --issue -d domain.example --standalone \
--cert-file /etc/proxmox-backup/proxy.pem \
--key-file /etc/proxmox-backup/proxy.key \
--fullchain-file /etc/proxmox-backup/proxy.pem \
--reloadcmd "chown root:backup /etc/proxmox-backup/proxy.pem /etc/proxmox-backup/proxy.key; chmod 640 /etc/proxmox-backup/proxy.pem /etc/proxmox-backup/proxy.key ; systemctl reload proxmox-backup-proxy"

TIP: With a trusted certificate clients do not require a fingerprint to verify the server. You can drop the fingerprint from all client configurations to avoid the need to update it every two-three months, after a new Let's Encrypt certificate is required.

Automatic Renewal

In order to automatically refresh the certificates and to reload the proxy service you also need to append the reload command as renew-hook in the generated cronjob (by running crontab -e) and editing so that the line looks like:

20 0 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh"  --renew-hook "chown root:backup /etc/proxmox-backup/proxy.pem /etc/proxmox-backup/proxy.key; chmod 640 /etc/proxmox-backup/proxy.pem /etc/proxmox-backup/proxy.key ; systemctl reload proxmox-backup-proxy" > /dev/null


Using Certificates from Proxmox VE

If you have installed Proxmox Backup Server and Proxmox VE on the same host, you can reuse the certificates provided by Proxmox VE's ACME/Let's Encrypt integration also for the Proxmox Backup Server proxy.

You only need to schedule the copying of the certificate and key after each renewal (e.g. by creating an appropriate cronjob or systemd-timer)

The necessary commands for copying are:

NODE=$(hostname)
cp /etc/pve/nodes/${NODE}/pveproxy-ssl.pem /etc/proxmox-backup/proxy.pem
cp /etc/pve/nodes/${NODE}/pveproxy-ssl.key /etc/proxmox-backup/proxy.key
chmod 640 /etc/proxmox-backup/proxy.key /etc/proxmox-backup/proxy.pem
chgrp backup /etc/proxmox-backup/proxy.key /etc/proxmox-backup/proxy.pem
systemctl reload proxmox-backup-proxy.service