Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Distinguish login failures by credential source and request path
pulse-triage[bot]c17d65074bc9
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.mdindex 726df71068..8c5cb2c99e 100644--- a/docs/TROUBLESHOOTING.md+++ b/docs/TROUBLESHOOTING.md@@ -14,9 +14,9 @@ matches how this self-hosted instance authenticates:Pulse administrator. If the administrator deliberately kept local login as afallback, they can open the Pulse URL with `?show_local=true`; this onlyreveals the existing local form and does not reset credentials.-- **Temporary lockout**: wait for the lockout to expire. Another signed-in- administrator can use the lockout reset in Pulse; password recovery is not- required.+- **Temporary lockout**: wait for the displayed lockout to expire. An authorised+ administrator can use the [manual recovery API](../SECURITY.md#manual-recovery-admin);+ this does not reset a password or bypass SSO.#### Recover the existing local administrator login@@ -190,13 +190,56 @@ origins, not a credential-bearing request or HAR file.### Authentication#### "Invalid username or password" after setup-- **Docker Compose**: Did you escape the `$` signs in your hash? Use `$$2a$$...`.-- **Truncated Hash**: Ensure your bcrypt hash is exactly 60 characters.++When the local login form reports this error, stop repeated password guesses:+failed attempts count against both the username and client IP. Privately check+the existing username and the active credential source. Deployment-supplied+`PULSE_AUTH_USER` and `PULSE_AUTH_PASS` take precedence over Pulse's generated+`.env`, so changing only that file may leave the running password unchanged.++A bcrypt hash must be complete (60 characters). Compose YAML interpolation,+Docker `--env-file` and Pulse's generated `.env` use different quoting rules;+do not blindly replace every `$` with `$$`. Follow the+[authentication-file guidance](CONFIGURATION.md#private-docker-authentication-file)+for your actual source, keeping hashes and resolved deployment configuration+private. If the password is genuinely lost, use+[deployment-specific recovery](#i-forgot-my-password), not setup or re-enrolment.#### Cannot login / 401 Unauthorized-- Clear browser cookies.-- Check if your IP is locked out (wait 15 mins).-- If another admin can log in, use `POST /api/security/reset-lockout` to clear the lockout for your username or IP.++Identify which request failed before clearing cookies or changing credentials:++- **Browser session:** a 401 on an ordinary UI request can mean a missing or+ expired session, not a wrong password. Open the same public Pulse URL in a+ fresh browser session and sign in through the configured method. Preserve any+ working administrator session; do not clear unrelated sites' cookies.+- **SSO or proxy login:** use the identity-provider or Pulse administrator's+ recovery path. Check the [proxy authentication guide](PROXY_AUTH.md) when the+ proxy signs you in but Pulse rejects the request. A local lockout reset does+ not repair an identity-provider account or missing trusted proxy headers.+- **Local login form:** an **Account locked** response gives the remaining wait.+ Lockout applies separately to username and client IP, normally for 15 minutes;+ clearing cookies does not reset it. A **Too many requests** response (429) is+ rate limiting, not proof that the password is wrong. Wait rather than retrying+ rapidly, restarting Pulse or disabling authentication.+- **API client:** a missing or invalid API token can cause 401 even when browser+ login works. Check the token's status and intended permissions privately.+ A 403 can instead mean insufficient permissions or failed CSRF protection;+ do not disable those checks or reset the password to repair API access. Use+ the [private header-file examples](../SECURITY.md#usage), never a token or+ session cookie pasted into a command or URL.++Manual lockout reset requires an authenticated administrator with+`settings:write` authority; session requests also require CSRF protection. The+[manual recovery API](../SECURITY.md#manual-recovery-admin) resets one username+or IP identifier at a time, not a password, SSO account or every lockout. Do not+assume resetting the username also clears a separately locked IP.++For a report, retain the time, sign-in method, redacted error, HTTP status and+request path (without query strings). Keep passwords, hashes, cookies, tokens,+full headers, **Copy as cURL** commands and network exports private. A 401 alone+does not justify deleting configuration, recreating the data volume or+re-enrolling agents.#### Audit Log verification shows unsigned eventsdiff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.mdindex 726df71068..8c5cb2c99e 100644--- a/frontend-modern/public/docs/TROUBLESHOOTING.md+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md@@ -14,9 +14,9 @@ matches how this self-hosted instance authenticates:Pulse administrator. If the administrator deliberately kept local login as afallback, they can open the Pulse URL with `?show_local=true`; this onlyreveals the existing local form and does not reset credentials.-- **Temporary lockout**: wait for the lockout to expire. Another signed-in- administrator can use the lockout reset in Pulse; password recovery is not- required.+- **Temporary lockout**: wait for the displayed lockout to expire. An authorised+ administrator can use the [manual recovery API](../SECURITY.md#manual-recovery-admin);+ this does not reset a password or bypass SSO.#### Recover the existing local administrator login@@ -190,13 +190,56 @@ origins, not a credential-bearing request or HAR file.### Authentication#### "Invalid username or password" after setup-- **Docker Compose**: Did you escape the `$` signs in your hash? Use `$$2a$$...`.-- **Truncated Hash**: Ensure your bcrypt hash is exactly 60 characters.++When the local login form reports this error, stop repeated password guesses:+failed attempts count against both the username and client IP. Privately check+the existing username and the active credential source. Deployment-supplied+`PULSE_AUTH_USER` and `PULSE_AUTH_PASS` take precedence over Pulse's generated+`.env`, so changing only that file may leave the running password unchanged.++A bcrypt hash must be complete (60 characters). Compose YAML interpolation,+Docker `--env-file` and Pulse's generated `.env` use different quoting rules;+do not blindly replace every `$` with `$$`. Follow the+[authentication-file guidance](CONFIGURATION.md#private-docker-authentication-file)+for your actual source, keeping hashes and resolved deployment configuration+private. If the password is genuinely lost, use+[deployment-specific recovery](#i-forgot-my-password), not setup or re-enrolment.#### Cannot login / 401 Unauthorized-- Clear browser cookies.-- Check if your IP is locked out (wait 15 mins).-- If another admin can log in, use `POST /api/security/reset-lockout` to clear the lockout for your username or IP.++Identify which request failed before clearing cookies or changing credentials:++- **Browser session:** a 401 on an ordinary UI request can mean a missing or+ expired session, not a wrong password. Open the same public Pulse URL in a+ fresh browser session and sign in through the configured method. Preserve any+ working administrator session; do not clear unrelated sites' cookies.+- **SSO or proxy login:** use the identity-provider or Pulse administrator's+ recovery path. Check the [proxy authentication guide](PROXY_AUTH.md) when the+ proxy signs you in but Pulse rejects the request. A local lockout reset does+ not repair an identity-provider account or missing trusted proxy headers.+- **Local login form:** an **Account locked** response gives the remaining wait.+ Lockout applies separately to username and client IP, normally for 15 minutes;+ clearing cookies does not reset it. A **Too many requests** response (429) is+ rate limiting, not proof that the password is wrong. Wait rather than retrying+ rapidly, restarting Pulse or disabling authentication.+- **API client:** a missing or invalid API token can cause 401 even when browser+ login works. Check the token's status and intended permissions privately.+ A 403 can instead mean insufficient permissions or failed CSRF protection;+ do not disable those checks or reset the password to repair API access. Use+ the [private header-file examples](../SECURITY.md#usage), never a token or+ session cookie pasted into a command or URL.++Manual lockout reset requires an authenticated administrator with+`settings:write` authority; session requests also require CSRF protection. The+[manual recovery API](../SECURITY.md#manual-recovery-admin) resets one username+or IP identifier at a time, not a password, SSO account or every lockout. Do not+assume resetting the username also clears a separately locked IP.++For a report, retain the time, sign-in method, redacted error, HTTP status and+request path (without query strings). Keep passwords, hashes, cookies, tokens,+full headers, **Copy as cURL** commands and network exports private. A 401 alone+does not justify deleting configuration, recreating the data volume or+re-enrolling agents.#### Audit Log verification shows unsigned eventsdiff --git a/scripts/tests/test_login_troubleshooting_docs.py b/scripts/tests/test_login_troubleshooting_docs.pynew file mode 100644index 0000000000..b9d28c4fc4--- /dev/null+++ b/scripts/tests/test_login_troubleshooting_docs.py@@ -0,0 +1,118 @@+#!/usr/bin/env python3+"""Keep existing login help distinct by credential source and failure path.++These are documentation/source-consistency checks, not authentication or+installed recovery tests. No credentials, network or service changes are used.+"""++from pathlib import Path+import unittest+++ROOT = Path(__file__).resolve().parents[2]+++def section(heading: str) -> str:+ text = (ROOT / "docs/TROUBLESHOOTING.md").read_text(encoding="utf-8")+ return " ".join(text.split(heading + "\n", 1)[1].split("\n#### ", 1)[0].split())+++class LoginTroubleshootingDocsTest(unittest.TestCase):+ def test_local_credentials_use_actual_precedence_and_file_format(self):+ text = section('#### "Invalid username or password" after setup')+ for expected in (+ "stop repeated password guesses", "username and client IP",+ "Deployment-supplied", "take precedence", "running password unchanged",+ "60 characters", "Compose YAML interpolation", "Docker `--env-file`",+ "different quoting rules", "do not blindly replace every `$` with `$$`",+ "CONFIGURATION.md#private-docker-authentication-file",+ "keeping hashes and resolved deployment configuration private",+ "#i-forgot-my-password", "not setup or re-enrolment",+ ):+ with self.subTest(statement=expected):+ self.assertIn(expected, text)+ self.assertNotIn("Use `$$2a$$...`", text)++ def test_browser_sso_and_api_failures_are_not_treated_as_one_password_problem(self):+ text = section("#### Cannot login / 401 Unauthorized")+ for expected in (+ "Browser session", "missing or expired session, not a wrong password",+ "same public Pulse URL", "fresh browser session",+ "Preserve any working administrator session", "SSO or proxy login",+ "PROXY_AUTH.md", "missing trusted proxy headers", "API client",+ "missing or invalid API token", "even when browser login works",+ "insufficient permissions or failed CSRF protection",+ "do not disable those checks or reset the password",+ ):+ with self.subTest(statement=expected):+ self.assertIn(expected, text)+ self.assertNotIn("- Clear browser cookies.", text)++ def test_lockout_rate_limit_and_identifier_reset_are_distinct(self):+ text = section("#### Cannot login / 401 Unauthorized")+ for expected in (+ "Account locked", "remaining wait", "separately to username and client IP",+ "clearing cookies does not reset it", "Too many requests", "429",+ "rate limiting, not proof that the password is wrong",+ "Wait rather than retrying rapidly, restarting Pulse or disabling authentication",+ "authenticated administrator", "`settings:write`", "CSRF protection",+ "resets one username or IP identifier at a time",+ "not a password, SSO account or every lockout",+ "Do not assume resetting the username also clears a separately locked IP",+ "../SECURITY.md#manual-recovery-admin",+ ):+ with self.subTest(statement=expected):+ self.assertIn(expected, text)++ def test_reporting_preserves_state_and_does_not_request_secrets(self):+ text = section("#### Cannot login / 401 Unauthorized")+ for expected in (+ "private header-file examples", "../SECURITY.md#usage",+ "never a token or session cookie pasted into a command or URL",+ "request path (without query strings)", "passwords, hashes, cookies, tokens",+ "full headers", "Copy as cURL", "network exports private",+ "does not justify deleting configuration, recreating the data volume",+ "re-enrolling agents",+ ):+ with self.subTest(statement=expected):+ self.assertIn(expected, text)+ self.assertNotIn("```", text) # Links to the established private recipe only.++ def test_guidance_still_matches_current_source_boundaries(self):+ router = (ROOT / "internal/api/router.go").read_text(encoding="utf-8")+ login = router.split("func (r *Router) handleLogin(", 1)[1].split(+ "// handleResetLockout", 1+ )[0]+ for marker in (+ "GetLockoutInfo(loginReq.Username)", "GetLockoutInfo(clientIP)",+ '"account_locked"', "http.StatusForbidden", '"remainingMinutes"',+ '"rate_limit"', "http.StatusTooManyRequests", '"invalid_credentials"',+ "http.StatusUnauthorized",+ ):+ self.assertIn(marker, login)+ reset = router.split("func (r *Router) handleResetLockout(", 1)[1].split(+ "// handleState", 1+ )[0]+ for marker in ("RequireAdmin", "ensureSettingsWriteScope", "ResetLockout(resetReq.Identifier)"):+ self.assertIn(marker, reset)+ security = (ROOT / "internal/api/security.go").read_text(encoding="utf-8")+ self.assertIn("lockoutDuration = 15 * time.Minute", security)+ auth = (ROOT / "internal/api/auth.go").read_text(encoding="utf-8")+ self.assertIn('"Invalid API token", http.StatusUnauthorized', auth)+ self.assertIn("ValidateAndExtendSession(cookie.Value)", auth)++ def test_quick_recovery_links_and_served_copy_do_not_invent_a_reset_ui(self):+ text = (ROOT / "docs/TROUBLESHOOTING.md").read_text(encoding="utf-8")+ quick = " ".join(text.split("### I forgot my password\n", 1)[1].split(+ "#### Recover the existing local administrator login", 1+ )[0].split())+ self.assertIn("../SECURITY.md#manual-recovery-admin", quick)+ self.assertNotIn("use the lockout reset in Pulse", quick)+ self.assertEqual(+ (ROOT / "docs/TROUBLESHOOTING.md").read_bytes(),+ (ROOT / "frontend-modern/public/docs/TROUBLESHOOTING.md").read_bytes(),+ )+++if __name__ == "__main__":+ unittest.main()