How to Install an SSL Certificate on Proxmox VE

Which certificate file does Proxmox actually use?

A Proxmox VE node keeps three certificate artefacts and only one of them is yours to write. /etc/pve/pve-root-ca.pem is the certificate authority the cluster generated for itself. /etc/pve/nodes/NODENAME/pve-ssl.pem is the node certificate that CA signed, and node-to-node traffic depends on it. /etc/pve/local/pveproxy-ssl.pem does not exist until you create it; once it does, pveproxy serves it to browsers instead.

That third file is an override rather than a replacement, which is the design decision worth understanding before you touch anything. Proxmox never stops using its internal PKI. You are not swapping the cluster’s identity for a commercial one; you are adding a second certificate that only the web proxy on port 8006 knows about, and leaving everything underneath as it was.

What you need before you start

Four things, and the install takes about a minute once you have them: a hostname the certificate covers and DNS that resolves it, the issued certificate in PEM form with its intermediates, the matching private key with no passphrase on it, and root access to the node either over SSH or through the shell in the web interface. Nothing here needs the host to be reachable from the public internet.

The passphrase point is worth taking seriously because it causes more failed installs than anything else. Proxmox does not prompt for one, so an encrypted key simply fails to parse and you get an unhelpful error about the key being invalid. If you generated the key yourself and chose a password, strip it first, the file is going onto a root-only filesystem on a machine that already has your hypervisor on it, and a passphrase nobody can type at boot buys nothing.

# strip the passphrase (asks for the old one once)
openssl pkey -in privkey-encrypted.pem -out privkey.pem

# these two hashes must be identical
openssl x509 -noout -modulus -in cert.pem | openssl sha256
openssl pkey  -noout -modulus -in privkey.pem | openssl sha256

If you have not generated the request yet, the guide to generating a CSR covers the openssl side, and certificate formats and conversions is the one to read if your CA sent you a .p7b or .pfx and Proxmox will not take it.

Which certificate to buy for a Proxmox host

The host needs a name a public CA is allowed to sign, and a great many Proxmox hosts do not have one. Since 11 November 2015 the CA/Browser Forum has prohibited publicly trusted certificates for internal server names and reserved IP addresses, so pve.lan, proxmox.local and 192.168.1.50 are all refused. Give the machine a name under a domain you own and the problem disappears.

This trips people up because the instinct is that a public certificate needs a public server. It does not. Point pve.example.com at 192.168.1.50 in whatever DNS your network uses, prove control of example.com to the CA with a DNS record, and you get a certificate for a host that has never accepted a connection from outside your building. If renaming the node is off the table, the options for internal server names are worth reading before you buy anything, because the answer there is usually a private CA rather than a public one.

Then it comes down to how many hosts you are covering. A single node needs a single-name certificate. Three nodes plus a backup server is where a wildcard certificate covering every subdomain usually wins, because you install the same file everywhere and adding a fourth node later needs no new certificate at all. If your hosts sit under different domains, a multi-domain certificate is the shape that fits instead, the comparison of wildcard and multi-domain coverage sets out which is which. Validation level barely matters for a management interface nobody outside the company sees, so a domain-validated certificate is usually the sensible purchase unless an auditor has asked for organisation details in the subject.

Installing it from the web interface

Select the node in the left-hand tree, open System then Certificates, and click Upload Custom Certificate. Paste the private key into the top box and the certificate chain into the bottom one, leaf first, then confirm. Proxmox writes the pveproxy-ssl pair, restarts pveproxy, and your browser session drops for a couple of seconds while it comes back on the new certificate.

Two details decide whether this works first time. The chain box wants the leaf certificate at the top and any intermediates underneath it, in order, with the root left out, a chain built the other way round loads in a desktop browser and then fails on anything with a stricter verifier, which is a miserable way to discover the mistake a week later. And the key box wants the decrypted key, for the reason covered above.

The same screen is where the existing certificates are listed, and it is worth a look before you upload anything. You will see the pve-ssl pair issued by the cluster CA and, once you have uploaded, the pveproxy-ssl pair alongside it. Both being present is the correct end state.

Installing it from the command line

pvenode cert set does the same job and is the one to use if you intend to script renewals. It takes the certificate and the key as file arguments, writes them to the pveproxy-ssl pair for the node you run it on, and with --restart reloads the proxy so the change takes effect immediately. --force is what lets it overwrite a custom certificate that is already there, so every run after the first one needs it.

# leaf first, then intermediates. No root.
cat cert.pem intermediate.pem > fullchain.pem

# install on THIS node and reload the web proxy
pvenode cert set fullchain.pem privkey.pem --force --restart

Verify from somewhere else rather than trusting the absence of an error. The check below asks the node what it is actually serving on port 8006 and prints the subject and the dates, which also tells you whether the chain arrived intact, a verify error: unable to get local issuer certificate in the output means an intermediate is missing from the file you installed.

openssl s_client -connect pve.example.com:8006 \
  -servername pve.example.com -showcerts </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates

What changes when you have a cluster

The certificate is shared and the installation is not. /etc/pve is the Proxmox cluster filesystem, so every node sees every other node’s directory under /etc/pve/nodes/. But /etc/pve/local is a runtime symlink that resolves to the directory named after the machine you are standing on, which means pvenode cert set writes somewhere different depending on where you run it. Run it on each node.

The consequence people find counterintuitive is that you can watch the certificate appear in /etc/pve/nodes/pve1/ from a shell on pve2, conclude the job is done, and still get a warning when you browse to pve2. It is genuinely the same filesystem. The node just only ever serves the file in its own directory.

Order matters in one situation. If you are building a new cluster and installing certificates at the same time, create the cluster and join the nodes first, then install certificates. Joining a node causes it to be issued a fresh pve-ssl certificate by the cluster CA, and doing that work in the other order means doing it twice.

for node in pve1 pve2 pve3; do
  scp fullchain.pem privkey.pem root@"$node".example.com:/root/
  ssh root@"$node".example.com \
    'pvenode cert set /root/fullchain.pem /root/privkey.pem --force --restart'
done

Leave a gap between nodes if anyone is using the interface, since each --restart drops sessions on that node for a second or two. Guests are unaffected either way, pveproxy serves the web interface and the API, and has nothing to do with whether a virtual machine is running.

Proxmox Backup Server is a separate job

Proxmox Backup Server has its own paths, its own service and its own port. The certificate and key go to /etc/proxmox-backup/proxy.pem and /etc/proxmox-backup/proxy.key, owned by root:backup with mode 0640, and proxmox-backup-proxy.service has to be restarted before anything changes on port 8007. None of the pvenode commands apply here.

The part that catches people is what happens on the other side. When you added the datastore to Proxmox VE, the storage entry recorded the backup server’s certificate fingerprint, and that stored value does not update itself when the certificate changes. The web interface stays perfectly happy; the backup job fails on connection at whatever hour it runs. Update the fingerprint under Datacenter then Storage then your PBS entry in the same maintenance window as the certificate and the problem never happens.

install -o root -g backup -m 0640 fullchain.pem /etc/proxmox-backup/proxy.pem
install -o root -g backup -m 0640 privkey.pem   /etc/proxmox-backup/proxy.key
systemctl restart proxmox-backup-proxy.service

# the value to paste into the Proxmox VE storage entry
openssl x509 -in /etc/proxmox-backup/proxy.pem -noout -fingerprint -sha256

Renewal after the 2026 lifetime cuts

Since 15 March 2026, publicly trusted TLS certificates max out at 200 days under CA/Browser Forum ballot SC-081v3, and the ceiling falls to 100 days in March 2027 and 47 days in March 2029. A three-node cluster that used to need one manual install round a year now needs two, then four, then eight. The install did not get harder. It got frequent.

Proxmox has an answer built in, and it is better known for Let’s Encrypt than it deserves to be. Version 8.2 added support for custom ACME directories with external account binding, so if your certificate authority publishes an ACME endpoint you can register against it with the key ID and HMAC key the CA issues you, and pve-daily-update.service will renew anything within 30 days of expiry without anyone logging in. The external account binding fields live in pvenode on the command line rather than in the web interface, which is why the feature is easy to miss.

# choose "Custom" at the directory prompt, paste your CA's ACME URL,
# then supply the EAB key id and HMAC key the CA gave you
pvenode acme account register default admin@example.com

# attach the name this node should be issued, then order
pvenode config set --acme domains=pve1.example.com
pvenode acme cert order

DNS-01 is the challenge type to use here, since it needs no inbound port 80 and works for a host that is not exposed at all; the comparison of ACME challenge types covers what each one proves. Where no ACME endpoint exists, the fallback is a short script that fetches the renewed files and ends in pvenode cert set --force --restart. Either way, the direction of travel is fixed, why automation stops being optional in 2027 and the full SC-081v3 timeline both set out what the calendar looks like from here.

When it goes wrong

Most Proxmox certificate failures are one of five things, and none of them locks you out permanently. SSH and the physical console never depend on the web certificate, so however badly the upload goes, you always have a way back in. That is worth remembering before the first attempt rather than during it.

The last row is the one that feels like a disaster and is not. Delete whatever you wrote over the node certificate, ask the cluster CA to reissue it, and restart the proxy. The cluster CA still exists. That is the whole reason the guidance is to leave it alone.

# remove the custom override if it is part of the mess
rm -f /etc/pve/local/pveproxy-ssl.pem /etc/pve/local/pveproxy-ssl.key

# reissue this node's pve-ssl pair from the cluster CA
pvecm updatecerts --force
systemctl restart pveproxy

That returns the node to the self-signed state it shipped in, warning and all, which is the right place to start again from. If a broken chain was the problem rather than a broken node certificate, how certificate chains break and how to repair them goes through the diagnosis properly.

FAQ