proxmox/docs/04-configuration/NPMPLUS_TLS_CLEANUP.md

NPMplus TLS Certificates – Cleanup Guide

Last Updated: 2026-01-31
Document Version: 1.0
Status: Active Documentation

---

Purpose: Clean up duplicate/inactive certificates in NPMplus and avoid creating more.

---

What happened

• request-npmplus-certificates.sh used to request a new certificate for every proxy host on every run.
• Failed or repeated runs created many Inactive certificate entries (same-day expiry, never assigned).
• Only certificates that were successfully issued and assigned to a proxy host show In use and a real expiry (e.g. 16 April 2026).

---

1. Clean up in NPMplus UI

1. Go to NPMplus → TLS Certificates.
2. Delete Inactive certificates:
   • Sort or scan for Status: Inactive.
   • Prefer deleting certs that:
     • Expire on the same day they were created (failed/duplicate requests), or
     • You know are not used by any proxy host.
   • Use the trash/delete action for each. Keep any cert that is actually in use.
3. Keep every certificate that shows In use and a sensible Expires date (e.g. April 2026).
4. Optional: Leave one or two clearly failed ones (e.g. same-day expiry) if you want to compare; you can delete them later.

Result: You should end up with roughly one cert per domain that has HTTPS (one In use cert per proxy host that uses SSL).

---

2. Assign certs to hosts that have none

If some Proxy Hosts still show HTTP only (e.g. rpc.d-bis.org, rpc2.d-bis.org, ws.rpc.d-bis.org, ws.rpc2.d-bis.org):

1. Option A – New cert for that host

   • Edit the proxy host → SSL tab.
   • Request a new SSL Certificate (Let's Encrypt), save.
   • After it succeeds, only one new cert will be created for that domain.

2. Option B – Reuse existing cert (same domain)

   • If you already have an In use cert for that domain, edit the proxy host → SSL tab.
   • Select that certificate and save.

---

3. Prevent the mess in future

• request-npmplus-certificates.sh has been updated to skip proxy hosts that already have a certificate (certificate_id set).
• So re-running the script will only request certs for hosts that still have HTTP only (no cert assigned), and will not create duplicate certs for hosts that already have one.

To request certs only for hosts that don’t have one yet:

./scripts/request-npmplus-certificates.sh

---

4. List status first (renew vs remove)

From the project root (with NPM_PASSWORD in .env):

./scripts/list-npmplus-certificates-status.sh

This lists every NPMplus TLS certificate with:

• In use: whether any proxy host uses it
• Expires / Days left: from API (or from container cert files if PROXMOX_HOST and NPMPLUS_VMID are set)
• Action: RENEW (in use and expiring soon or unknown), KEEP (in use, not expiring soon), REMOVE (not assigned to any host)

Use this to see which certs to renew (in NPM UI or request script) and which to remove (cleanup script below).

---

5. Automated cleanup (recommended)

From the project root (with NPM_PASSWORD in .env):

# Dry run – show what would be deleted (no changes)
./scripts/cleanup-npmplus-inactive-certificates.sh true

# Actually remove all certificates not assigned to any proxy host
./scripts/cleanup-npmplus-inactive-certificates.sh false

The script uses the NPM API: it finds certs that no proxy host references and deletes them. Only unused certificates are removed; certs that are In use are left as-is.

---

6. Summary

Action	Where
List status (renew vs remove)	./scripts/list-npmplus-certificates-status.sh
Delete Inactive / same-day-expiry certs	NPMplus → TLS Certificates or cleanup-npmplus-inactive-certificates.sh
Keep all "In use" certs (e.g. expiry April 2026)	Do not delete
Assign cert to hosts still "HTTP only"	Proxy Hosts → Edit → SSL
Future runs of request script	Only request for hosts with no cert (no duplicates)

See also: scripts/list-npmplus-certificates-status.sh, scripts/request-npmplus-certificates.sh, docs/04-configuration/NEXT_STEPS_CHAIN138_RPC.md (troubleshooting).