mirror of
https://github.com/MacRimi/ProxMenux.git
synced 2026-11-05 12:22:08 +00:00
docs(web): fix Monitor API paths and token and SSL location
This commit is contained in:
@@ -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>."
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
|
|||||||
@@ -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",
|
||||||
|
|||||||
Reference in New Issue
Block a user