docs(web): fix Monitor API paths and token and SSL location

This commit is contained in:
Manuel Escalante
2026-11-01 14:05:13 +01:00
parent 24d069e1dd
commit 398ca55247
6 changed files with 13 additions and 13 deletions
@@ -284,7 +284,7 @@
"heading": "API tokens (long-lived)", "heading": "API tokens (long-lived)",
"intro": "Browser sessions expire after 24 hours. For unattended integrations (Homepage widgets, Home Assistant sensors, Grafana scrapers, Uptime Kuma probes…) you generate a separate <strong>API token</strong> that lives 365 days. The token is a JWT signed with the same secret as the session token, but its <code>token_name</code> claim makes it easy to track and revoke individually.", "intro": "Browser sessions expire after 24 hours. For unattended integrations (Homepage widgets, Home Assistant sensors, Grafana scrapers, Uptime Kuma probes…) you generate a separate <strong>API token</strong> that lives 365 days. The token is a JWT signed with the same secret as the session token, but its <code>token_name</code> claim makes it easy to track and revoke individually.",
"imageAlt": "API tokens panel showing the token list with name, prefix, created date and expiry", "imageAlt": "API tokens panel showing the token list with name, prefix, created date and expiry",
"imageCaption": "The API tokens list under Settings — name, prefix (last 4 chars are shown for identification), created and expiry dates, revoke action.", "imageCaption": "The API tokens list under Admin → Security — name, prefix (last 4 chars are shown for identification), created and expiry dates, revoke action.",
"generateTitle": "Generate a token", "generateTitle": "Generate a token",
"generateIntro": "From the dashboard:", "generateIntro": "From the dashboard:",
"generateSteps": [ "generateSteps": [
@@ -310,7 +310,7 @@
"intro": "Two paths to TLS:", "intro": "Two paths to TLS:",
"items": [ "items": [
"<strong>Reverse proxy (recommended).</strong> Terminate TLS on Nginx / Caddy / Traefik and forward HTTP on port 8008 to the Flask process. Snippets below.", "<strong>Reverse proxy (recommended).</strong> Terminate TLS on Nginx / Caddy / Traefik and forward HTTP on port 8008 to the Flask process. Snippets below.",
"<strong>Direct HTTPS in the AppImage.</strong> Configure a certificate with <code>POST /api/ssl/configure</code> (UI: <strong>Settings → SSL</strong>). The HTTPS path uses <code>gevent.pywsgi</code> with its standard handler; flask-sock handles WebSocket upgrades for WSS. Certificate paths are stored in the SSL configuration." "<strong>Direct HTTPS in the AppImage.</strong> Configure a certificate with <code>POST /api/ssl/configure</code> (UI: <strong>Admin → Security → SSL / HTTPS</strong>). The HTTPS path uses <code>gevent.pywsgi</code> with its standard handler; flask-sock handles WebSocket upgrades for WSS. Certificate paths are stored in the SSL configuration."
], ],
"calloutTitle": "Direct HTTPS limitations", "calloutTitle": "Direct HTTPS limitations",
"calloutBody": "The Monitor can use a Proxmox-managed certificate or custom certificate files. It does not issue ACME certificates itself. For automatic issuance and renewal, use Proxmox ACME or a reverse proxy such as Caddy, Traefik or Nginx, and ensure renewed certificates are loaded." "calloutBody": "The Monitor can use a Proxmox-managed certificate or custom certificate files. It does not issue ACME certificates itself. For automatic issuance and renewal, use Proxmox ACME or a reverse proxy such as Caddy, Traefik or Nginx, and ensure renewed certificates are loaded."
@@ -183,7 +183,7 @@
}, },
{ {
"card": "SSL / HTTPS", "card": "SSL / HTTPS",
"endpoint": "/api/auth/ssl/*", "endpoint": "/api/ssl/*",
"source": "<code>openssl x509</code> on <code>/etc/pve/local/pve-ssl.pem</code> + <code>/etc/proxmenux/ssl_config.json</code>." "source": "<code>openssl x509</code> on <code>/etc/pve/local/pve-ssl.pem</code> + <code>/etc/proxmenux/ssl_config.json</code>."
}, },
{ {
@@ -304,7 +304,7 @@
}, },
{ {
"card": "Storage / interface exclusions", "card": "Storage / interface exclusions",
"endpoint": "/api/storage/exclusions, /api/network/exclusions", "endpoint": "/api/health/storage-exclusions, /api/health/interface-exclusions",
"source": "SQLite tables <code>excluded_storages</code> and <code>excluded_interfaces</code>." "source": "SQLite tables <code>excluded_storages</code> and <code>excluded_interfaces</code>."
}, },
{ {
+1 -1
View File
@@ -113,7 +113,7 @@
"api": { "api": {
"heading": "REST API and integrations", "heading": "REST API and integrations",
"intro": "The dashboard’s REST endpoints expose monitoring data as JSON over HTTP/HTTPS for Homepage widgets, Home Assistant sensors, Uptime Kuma probes and custom scripts. Grafana can use the separate Prometheus text exporter at <code>/api/prometheus</code>. Requests can be made with <code>curl</code>.", "intro": "The dashboard’s REST endpoints expose monitoring data as JSON over HTTP/HTTPS for Homepage widgets, Home Assistant sensors, Uptime Kuma probes and custom scripts. Grafana can use the separate Prometheus text exporter at <code>/api/prometheus</code>. Requests can be made with <code>curl</code>.",
"tokens": "Long-lived API tokens (365 days) are generated from <strong>Settings → API Access Tokens</strong> or via <code>POST /api/auth/generate-api-token</code>.", "tokens": "Long-lived API tokens (365 days) are generated from <strong>Admin → Security → API Tokens</strong> or via <code>POST /api/auth/generate-api-token</code>.",
"bearer": "Send tokens as <code>Authorization: Bearer …</code>. <code>/api/health</code> also expects the bearer header, so uptime probes need a read_only token. Routes under <code>/api/auth/*</code> include both public setup/login/status routes and protected account/token management routes; they are not all anonymous.", "bearer": "Send tokens as <code>Authorization: Bearer …</code>. <code>/api/health</code> also expects the bearer header, so uptime probes need a read_only token. Routes under <code>/api/auth/*</code> include both public setup/login/status routes and protected account/token management routes; they are not all anonymous.",
"catalog": "The full endpoint catalog, token rotation guidance and security best-practices live in <linkApi>API Reference</linkApi>; ready-made examples for Homepage, Home Assistant, Grafana, Uptime Kuma and a generic cURL pattern are in <linkIntegrations>Integrations</linkIntegrations>." "catalog": "The full endpoint catalog, token rotation guidance and security best-practices live in <linkApi>API Reference</linkApi>; ready-made examples for Homepage, Home Assistant, Grafana, Uptime Kuma and a generic cURL pattern are in <linkIntegrations>Integrations</linkIntegrations>."
}, },
@@ -20,13 +20,13 @@
"heading": "Authentication: the one thing every recipe needs", "heading": "Authentication: the one thing every recipe needs",
"intro": "Most endpoints used by these integrations are authenticated. You have two ways to satisfy that requirement.", "intro": "Most endpoints used by these integrations are authenticated. You have two ways to satisfy that requirement.",
"optAtitle": "Option A — API token (recommended for integrations)", "optAtitle": "Option A — API token (recommended for integrations)",
"optAbody1": "Open the dashboard and go to <strong>Settings → Security → API Tokens</strong>. Click <em>Generate token</em>, give it a name (e.g. <em>homepage</em>, <em>home-assistant</em>, <em>prometheus</em>), and copy the token — it's shown <em>once</em>. Long-lived (one-year expiry by default), individually revocable, and what you should be using for any non-browser client.", "optAbody1": "Open the dashboard and go to <strong>Admin → Security → API Tokens</strong>. Click <em>Generate token</em>, give it a name (e.g. <em>homepage</em>, <em>home-assistant</em>, <em>prometheus</em>), and copy the token — it's shown <em>once</em>. Long-lived (one-year expiry by default), individually revocable, and what you should be using for any non-browser client.",
"optAbody2": "From that point every request is just:", "optAbody2": "From that point every request is just:",
"optBtitle": "Option B — login flow (username + password)", "optBtitle": "Option B — login flow (username + password)",
"optBbody": "Useful for scripts that authenticate as a human user. The returned token is short-lived; most integrations should prefer Option A.", "optBbody": "Useful for scripts that authenticate as a human user. The returned token is short-lived; most integrations should prefer Option A.",
"outro": "The TOTP field is only required when 2FA is enabled on the account. Token rotation, revocation, password policy and the audit log live in <link>Access & Authentication</link>.", "outro": "The TOTP field is only required when 2FA is enabled on the account. Token rotation, revocation, password policy and the audit log live in <link>Access & Authentication</link>.",
"httpsTitle": "Using HTTPS instead of HTTP", "httpsTitle": "Using HTTPS instead of HTTP",
"httpsIntro": "Every recipe below uses <code>http://</code> in the URLs to keep the examples short. If you've enabled TLS on the Monitor (<strong>Settings → Security → SSL/HTTPS</strong>), swap <code>http://</code> for <code>https://</code> in every URL — that's the only change. Two notes specific to certain tools:", "httpsIntro": "Every recipe below uses <code>http://</code> in the URLs to keep the examples short. If you've enabled TLS on the Monitor (<strong>Admin → Security → SSL / HTTPS</strong>), swap <code>http://</code> for <code>https://</code> in every URL — that's the only change. Two notes specific to certain tools:",
"httpsItems": [ "httpsItems": [
"<strong>Self-signed certificates.</strong> Home Assistant's <code>rest:</code> integration verifies TLS by default. If the Monitor is using its own self-signed cert, add <code>verify_ssl: false</code> to each REST block (alongside <code>scan_interval:</code>), or import the Monitor's CA into HA's trust store. Same for any tool that refuses untrusted certs.", "<strong>Self-signed certificates.</strong> Home Assistant's <code>rest:</code> integration verifies TLS by default. If the Monitor is using its own self-signed cert, add <code>verify_ssl: false</code> to each REST block (alongside <code>scan_interval:</code>), or import the Monitor's CA into HA's trust store. Same for any tool that refuses untrusted certs.",
"<strong>Prometheus</strong> already has <code>scheme: https</code> ready in the scrape config below; uncomment / leave it as <code>https</code> if TLS is enabled on the Monitor." "<strong>Prometheus</strong> already has <code>scheme: https</code> ready in the scrape config below; uncomment / leave it as <code>https</code> if TLS is enabled on the Monitor."
@@ -43,7 +43,7 @@
"basicTitle": "Basic widget — no authentication", "basicTitle": "Basic widget — no authentication",
"basicIntro": "Use this when ProxMenux Monitor is on a trusted network and you haven't enabled authentication on the Monitor side yet. The simplest possible <code>services.yaml</code> entry:", "basicIntro": "Use this when ProxMenux Monitor is on a trusted network and you haven't enabled authentication on the Monitor side yet. The simplest possible <code>services.yaml</code> entry:",
"authedTitle": "Authenticated widget", "authedTitle": "Authenticated widget",
"authedIntro": "Generate an API token in <strong>Settings → Security → API Tokens</strong> on the Monitor, copy it, and paste it into the <code>Authorization</code> header below — replace the example token shown after <code>Bearer</code> with the one you just copied:", "authedIntro": "Generate an API token in <strong>Admin → Security → API Tokens</strong> on the Monitor, copy it, and paste it into the <code>Authorization</code> header below — replace the example token shown after <code>Bearer</code> with the one you just copied:",
"authedOutro": "Restart Homepage and the card lights up with live values. Reuse the same token across all Homepage widgets pointing at the same ProxMenux Monitor host.", "authedOutro": "Restart Homepage and the card lights up with live values. Reuse the same token across all Homepage widgets pointing at the same ProxMenux Monitor host.",
"multiTitle": "Multi-widget setup — system, storage, network", "multiTitle": "Multi-widget setup — system, storage, network",
"multiIntro": "For a richer view, render three separate cards backed by different endpoints — one for system metrics, one for storage, one for network. Use the same token in every card; it's the same Monitor instance.", "multiIntro": "For a richer view, render three separate cards backed by different endpoints — one for system metrics, one for storage, one for network. Use the same token in every card; it's the same Monitor instance.",
@@ -12,13 +12,13 @@
}, },
"intro": { "intro": {
"title": "What this page covers", "title": "What this page covers",
"body": "How to switch the Monitor from HTTP to HTTPS in the Settings → Security panel, what each certificate source actually points at on disk, how the Proxmox option behaves when the host has a Let's Encrypt cert, and how to set custom paths if you manage certs outside Proxmox." "body": "How to switch the Monitor from HTTP to HTTPS in the Admin → Security panel, what each certificate source actually points at on disk, how the Proxmox option behaves when the host has a Let's Encrypt cert, and how to set custom paths if you manage certs outside Proxmox."
}, },
"wheresetting": { "wheresetting": {
"heading": "Where the setting lives", "heading": "Where the setting lives",
"body": "Open the Monitor and go to <strong>Settings → Security → HTTPS / SSL</strong>. The panel shows the current state (HTTP or HTTPS), and on a host without HTTPS yet it lists the certificate sources the Monitor was able to detect.", "body": "Open the Monitor and go to <strong>Admin → Security → SSL / HTTPS</strong>. The panel shows the current state (HTTP or HTTPS), and on a host without HTTPS yet it lists the certificate sources the Monitor was able to detect.",
"imageAlt": "Settings → Security → HTTPS / SSL panel in the Monitor showing the HTTPS-off state, the auto-detected Proxmox certificate (subject, issuer, expiry) and the Use Custom Certificate option", "imageAlt": "Admin → Security → SSL / HTTPS panel in the Monitor showing the HTTPS-off state, the auto-detected Proxmox certificate (subject, issuer, expiry) and the Use Custom Certificate option",
"caption": "Settings → Security → HTTPS / SSL panel before activation. The Monitor surfaces the cert Proxmox itself is using and offers it as a one-click source." "caption": "Admin → Security → SSL / HTTPS panel before activation. The Monitor surfaces the cert Proxmox itself is using and offers it as a one-click source."
}, },
"twoways": { "twoways": {
"heading": "Two ways to enable HTTPS", "heading": "Two ways to enable HTTPS",
@@ -117,7 +117,7 @@
}, },
"switchToHttps": { "switchToHttps": {
"heading": "Switch the Monitor to HTTPS", "heading": "Switch the Monitor to HTTPS",
"bodyRich": "Once <code>/etc/pve/local/pveproxy-ssl.pem</code> is signed by Let's Encrypt, the Monitor side is one click: open <strong>Settings → Security → HTTPS / SSL</strong>, confirm the issuer shown in the detected-certificate panel reads <em>Let's Encrypt</em> (and not the local Proxmox CA), and click <strong>Use Proxmox Certificate</strong>. The Monitor service restarts and the next browser load is HTTPS on port 8008 — no certificate warning, since the chain is publicly trusted. Later Proxmox ACME renewals are validated and selected during the next new TLS connection; there is no recurring certificate poller or renewal-time service restart. <strong>Update certificate</strong> remains available in Security as an explicit diagnostic and recovery action." "bodyRich": "Once <code>/etc/pve/local/pveproxy-ssl.pem</code> is signed by Let's Encrypt, the Monitor side is one click: open <strong>Admin → Security → SSL / HTTPS</strong>, confirm the issuer shown in the detected-certificate panel reads <em>Let's Encrypt</em> (and not the local Proxmox CA), and click <strong>Use Proxmox Certificate</strong>. The Monitor service restarts and the next browser load is HTTPS on port 8008 — no certificate warning, since the chain is publicly trusted. Later Proxmox ACME renewals are validated and selected during the next new TLS connection; there is no recurring certificate poller or renewal-time service restart. <strong>Update certificate</strong> remains available in Security as an explicit diagnostic and recovery action."
}, },
"custom": { "custom": {
"heading": "Custom certificate — when to use it", "heading": "Custom certificate — when to use it",