Replace the Proxmox VE SSL Certificate (pveproxy)

The Proxmox VE web interface and API are served by pveproxy on port 8006 of each node. By default they use a node certificate signed by the cluster's own CA, which browsers do not trust. A custom certificate from a public or internal CA is stored per node as /etc/pve/nodes/<node>/pveproxy-ssl.pem and pveproxy-ssl.key and takes precedence over the default. (/etc/pve/local points to the current node's directory.)

Before you beginCopy Anchor Link

• Prepare a PEM chain file with the node certificate first, followed by the intermediate certificates - for example by concatenating the Base64/PEM files from your CA: cat node.crt intermediate.crt > fullchain.pem.

• Prepare the matching private key without a passphrase. Proxmox starts pveproxy unattended, so an encrypted key does not work. Remove the passphrase with:

  Copy Text

  openssl pkey -in encrypted.key -out private.key
  chmod 600 private.key

  Keep the unencrypted key only on the node and delete temporary copies afterwards.

• Make sure the SAN covers the FQDN of every node the certificate is used on. One certificate with all node names, or a wildcard, can be installed on every node.

• Back up the current custom certificate, if there is one:

  Copy Text

  cp /etc/pve/local/pveproxy-ssl.pem /etc/pve/local/pveproxy-ssl.key /root/

• Check that the cluster is healthy (pvecm status shows quorum), and keep SSH or console access.

Never replace or edit the files Proxmox manages itself:

Proxmox uses these for cluster-internal trust. The custom certificate sits next to them and never replaces them.

Step-by-step certificate replacementCopy Anchor Link

Do this on one node at a time, with either the web UI or the shell.

In the web UI: select the node, then System > Certificates > Upload Custom Certificate. Paste or load the chain file and the private key. If a custom or ACME certificate is already installed, confirm that it may be overwritten. The page reloads after pveproxy restarts.

On the node's shell: copy both files to the node (for example with scp), then:

pvenode cert set /root/fullchain.pem /root/private.key --restart 1

--restart 1 restarts pveproxy so the new certificate is served. If a custom or ACME certificate is already installed, the command refuses to overwrite it unless you add --force 1 - add it when replacing a certificate on purpose, and be aware that it also replaces a working ACME certificate.

Then, for either way:

1. Check what the node now uses:

   Copy Text

   pvenode cert info

2. Repeat on the next node. Each node has its own custom certificate; installing it on one node does not change the others.

Let ACME renew it insteadCopy Anchor Link

Proxmox VE has a built-in ACME client. With Let's Encrypt or another ACME CA it can issue and renew the node certificate itself, so there is nothing to replace by hand:

• HTTP-01: validated by Proxmox's own web server on port 80. The node's FQDN must resolve publicly to the node, and port 80 must be reachable from the CA.
• DNS-01: validated through a DNS API plugin (Proxmox uses the acme.sh plugin set), configured with your DNS provider's API credentials. The node does not have to be reachable from the internet.

Register an ACME account under Datacenter > ACME (and add a DNS plugin there if you use DNS-01). Then, on each node, add its domains under System > Certificates in the ACME section and order the certificate - in the UI, or with:

pvenode acme cert order

Proxmox renews ACME certificates automatically when they are within 30 days of expiry. ACME and a manually uploaded custom certificate are alternatives: while a custom certificate is installed, the order only replaces it with --force 1.

Product-specific considerationsCopy Anchor Link

Restarting pveproxy interrupts web UI and API connections on that node for a moment, so update nodes one at a time. Console, SPICE and cluster-internal trust depend on the Proxmox-managed certificates, which the custom web certificate does not replace.

Verify the new certificateCopy Anchor Link

systemctl status pveproxy
pvenode cert info
openssl s_client -connect node1.example.com:8006 -servername node1.example.com -showcerts </dev/null

In the output, check the subject and SAN, the issuer, the expiry date and that the intermediate is sent. Then log in to the UI of every node, and test API clients and the VM console.

RollbackCopy Anchor Link

Put the backed-up certificate back with the same command, forcing the overwrite:

pvenode cert set /root/pveproxy-ssl.pem /root/pveproxy-ssl.key --force 1 --restart 1

Or remove the custom certificate so the node falls back to its cluster-signed default. The argument 1 restarts pveproxy:

pvenode cert delete 1

Both act on the node you run them on.

Common problemsCopy Anchor Link

• The private key still has a passphrase, so pveproxy cannot use it.
• Only one cluster node was updated.
• An administrator overwrote pve-ssl.* or the cluster CA files instead of uploading a custom certificate.
• The chain is in the wrong order, or the node FQDN is missing from the SAN.
• A forced upload replaced a working ACME certificate, or a forced ACME order replaced the custom one.

Automating certificate replacement with aethercertCopy Anchor Link

The aethercert Proxmox target uploads a leaf-first full chain and unencrypted key to the selected node through its REST API, with force and restart enabled. Create a target per node that serves the UI/API.

See Deploy targets for the fields this preset takes, what it needs on the host, and how far it has been verified.

SourcesCopy Anchor Link

• Proxmox VE: certificate management
• Proxmox VE Administration Guide: certificate management
• Proxmox pvenode command reference