How to change Certificate on Proxmox VE

Learn how to manually upload a custom TLS certificate on Proxmox VE, preserve cluster CA files, restart pveproxy safely, update every node, and verify.

The Proxmox VE API and web UI are served by pveproxy on each node. A custom public certificate uses node-local pveproxy-ssl.pem and pveproxy-ssl.key; it must not replace the cluster's automatically generated pve-ssl.* or root CA files.

Before you begin

Prepare a leaf-first PEM certificate chain and an unencrypted matching private key. Record every cluster node/FQDN and the old custom material. Verify quorum and node health, and retain SSH/console access.

Step-by-step certificate replacement

In the web UI select Node > System > Certificates > Upload Custom Certificate. Upload the full certificate chain and private key, choose the overwrite option for an existing custom certificate, and confirm restart when offered.

Or use the node management command with version-matched syntax:

pvenode cert set fullchain.pem private.key --force --restart

Repeat on every node. /etc/pve/local is a node-specific symlink to /etc/pve/nodes/<node>, so one node's custom certificate is not a cluster-wide wildcard replacement.
Confirm pveproxy restarted cleanly. Do not edit /etc/pve/local/pve-ssl.pem, /etc/pve/local/pve-ssl.key, or the cluster CA files.

Product-specific considerations

The custom key cannot be password protected because the proxy must start unattended. Restarting pveproxy interrupts API/UI connections on that node; update nodes one at a time. Console/SPICE and internal cluster trust also depend on Proxmox-managed certificates, which this external web certificate must not replace.

Verify the new certificate

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

Log into every node UI and test API clients and console access.

Rollback

Upload/set the old full chain and key with the same supported operation and restart pveproxy. If removing a custom certificate, use pvenode cert delete according to the installed version so Proxmox falls back to its managed node certificate.

Common problems

Encrypted private key prevents unattended proxy startup.
Only one cluster node is updated.
Administrator overwrites pve-ssl.* or cluster CA files.
Chain order is wrong or node FQDN is absent from SANs.

Automating certificate replacement with aethercert

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.