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
Explain startup import without promising safe first-run recovery
pulse-triage[bot]9c1b4ef8ddb9
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.mdindex 606e8ac58d..a046044993 100644--- a/docs/CONFIGURATION.md+++ b/docs/CONFIGURATION.md@@ -504,20 +504,61 @@ These are stored in `system.json` and managed via the UI.### Auto-Import (Bootstrap)-You can auto-import an encrypted backup on first startup. This is useful for automated provisioning and test environments.+Startup import is for deliberately provisioning an **isolated destination**,+not resetting an existing installation. It uses the same encrypted+[configuration-transfer scope](MIGRATION.md#configuration-transfer) as the+Recovery settings form, not a full-state backup. Included settings and API-token+records are **replaced, not merged**; imported SSO settings can also change access.++The startup gate checks for `nodes.enc` in the effective data directory+(`PULSE_DATA_DIR`, or the deployment default). If that file exists, startup+skips import. **This is a file-presence check, not a record of the first run.**+Other existing settings, API-token records or session files alone do not prevent+an import attempt. Do not delete `nodes.enc`, change the data path or remove+credentials to force one; resolve an unexpected path or access failure first.+For an existing installation, use the+[reviewed transfer procedure](MIGRATION.md#transfer-the-included-configuration)+instead, with a private backup of the destination before replacing settings.| Variable | Description || ---------- | ------------- |-| `PULSE_INIT_CONFIG_DATA` | Base64 or raw contents of an export bundle (auto-imports on first start) |-| `PULSE_INIT_CONFIG_FILE` | Path to an export bundle on disk (auto-imports on first start) |+| `PULSE_INIT_CONFIG_DATA` | Encrypted export contents; used only when `PULSE_INIT_CONFIG_FILE` is unset |+| `PULSE_INIT_CONFIG_FILE` | Path to the private encrypted export, readable by the Pulse service; takes precedence over `PULSE_INIT_CONFIG_DATA` || `PULSE_INIT_CONFIG_PASSPHRASE` | Passphrase for the export bundle (required) |-> **Note**: `PULSE_INIT_CONFIG_URL` is only supported by the hidden `pulse config auto-import` command, not by the server startup auto-import.--Configuration import restores server-side agent credentials, but it cannot-change the primary Pulse URL persisted on remote agents. When restoring onto a-server with a different address, retarget those agents after import. See-[Moving Pulse to a new address](UNIFIED_AGENT.md#moving-pulse-to-a-new-address).+An unreadable or invalid file fails the attempt; it does **not** fall back to+the data variable. `PULSE_INIT_CONFIG_URL` is not supported by server startup;+the separate hidden `pulse config auto-import` command has a different path.++Keep the export owner-only and its passphrase in the deployment's private+credential source, separate from the backup. Do not put a passphrase or bundle+in command arguments, URLs, shared Compose files, logs or issue reports;+base64 is not redaction. Startup has no passphrase-file variable. For an+interactive transfer, use the authenticated Recovery form instead.++Before enabling startup import, preserve the intact source and any useful+destination state. Isolate the trial destination from agents and notification+destinations: imported settings can activate monitoring and delivery. Keep only+one active installation at cutover, with independent outage coverage.++**A running server is not proof that import succeeded.** A returned import+error is logged and startup continues with normal configuration loading, which+can itself fail. Review the existing error privately, stop the trial destination+on an unexpected result, and reconcile its state before another attempt. Do not+repeat import, replay notifications or induce a workload action to test recovery.+After verifying the intended settings and access, remove only the three+`PULSE_INIT_CONFIG_*` settings above from the deployment's managed source so a+later start cannot reuse them. Apply environment changes through the existing+deployment during suitable maintenance, preserving its image, data and other+credentials; a Docker restart alone does not apply a changed environment.++Configuration transfer includes API-token records, but **not server-side agent+inventory or enrolment state**, local login credentials or monitoring history.+It cannot change the primary URL saved on remote agents. If the address changes,+follow [agent retargeting](UNIFIED_AGENT.md#moving-pulse-to-a-new-address),+preserving each agent's identity, credential and TLS trust. Verify fresh admission+and ordinary reports before retiring the source; imported records alone do not+establish agent recovery.### Developer/Test Overrides (Environment Variables)diff --git a/docs/MIGRATION.md b/docs/MIGRATION.mdindex 8343f97b89..eb0c8e1fc4 100644--- a/docs/MIGRATION.md+++ b/docs/MIGRATION.md@@ -33,6 +33,12 @@ settings included above. Imported API-token records retain their scopes andexpiry; they do not reveal the original tokens or transfer every agent's state.SSO configuration **is included**, even though local login credentials are not.+Automated provisioning uses the same limited scope. Read the+[startup-import gate and safeguards](CONFIGURATION.md#auto-import-bootstrap)+before setting bootstrap variables: an existing installation without+`nodes.enc` is not protected by a first-run marker, and normal startup after+an import error does not confirm a successful transfer.+### Full-state recoveryIf you need the same installation's history and excluded state, retain adiff --git a/frontend-modern/public/docs/CONFIGURATION.md b/frontend-modern/public/docs/CONFIGURATION.mdindex 606e8ac58d..a046044993 100644--- a/frontend-modern/public/docs/CONFIGURATION.md+++ b/frontend-modern/public/docs/CONFIGURATION.md@@ -504,20 +504,61 @@ These are stored in `system.json` and managed via the UI.### Auto-Import (Bootstrap)-You can auto-import an encrypted backup on first startup. This is useful for automated provisioning and test environments.+Startup import is for deliberately provisioning an **isolated destination**,+not resetting an existing installation. It uses the same encrypted+[configuration-transfer scope](MIGRATION.md#configuration-transfer) as the+Recovery settings form, not a full-state backup. Included settings and API-token+records are **replaced, not merged**; imported SSO settings can also change access.++The startup gate checks for `nodes.enc` in the effective data directory+(`PULSE_DATA_DIR`, or the deployment default). If that file exists, startup+skips import. **This is a file-presence check, not a record of the first run.**+Other existing settings, API-token records or session files alone do not prevent+an import attempt. Do not delete `nodes.enc`, change the data path or remove+credentials to force one; resolve an unexpected path or access failure first.+For an existing installation, use the+[reviewed transfer procedure](MIGRATION.md#transfer-the-included-configuration)+instead, with a private backup of the destination before replacing settings.| Variable | Description || ---------- | ------------- |-| `PULSE_INIT_CONFIG_DATA` | Base64 or raw contents of an export bundle (auto-imports on first start) |-| `PULSE_INIT_CONFIG_FILE` | Path to an export bundle on disk (auto-imports on first start) |+| `PULSE_INIT_CONFIG_DATA` | Encrypted export contents; used only when `PULSE_INIT_CONFIG_FILE` is unset |+| `PULSE_INIT_CONFIG_FILE` | Path to the private encrypted export, readable by the Pulse service; takes precedence over `PULSE_INIT_CONFIG_DATA` || `PULSE_INIT_CONFIG_PASSPHRASE` | Passphrase for the export bundle (required) |-> **Note**: `PULSE_INIT_CONFIG_URL` is only supported by the hidden `pulse config auto-import` command, not by the server startup auto-import.--Configuration import restores server-side agent credentials, but it cannot-change the primary Pulse URL persisted on remote agents. When restoring onto a-server with a different address, retarget those agents after import. See-[Moving Pulse to a new address](UNIFIED_AGENT.md#moving-pulse-to-a-new-address).+An unreadable or invalid file fails the attempt; it does **not** fall back to+the data variable. `PULSE_INIT_CONFIG_URL` is not supported by server startup;+the separate hidden `pulse config auto-import` command has a different path.++Keep the export owner-only and its passphrase in the deployment's private+credential source, separate from the backup. Do not put a passphrase or bundle+in command arguments, URLs, shared Compose files, logs or issue reports;+base64 is not redaction. Startup has no passphrase-file variable. For an+interactive transfer, use the authenticated Recovery form instead.++Before enabling startup import, preserve the intact source and any useful+destination state. Isolate the trial destination from agents and notification+destinations: imported settings can activate monitoring and delivery. Keep only+one active installation at cutover, with independent outage coverage.++**A running server is not proof that import succeeded.** A returned import+error is logged and startup continues with normal configuration loading, which+can itself fail. Review the existing error privately, stop the trial destination+on an unexpected result, and reconcile its state before another attempt. Do not+repeat import, replay notifications or induce a workload action to test recovery.+After verifying the intended settings and access, remove only the three+`PULSE_INIT_CONFIG_*` settings above from the deployment's managed source so a+later start cannot reuse them. Apply environment changes through the existing+deployment during suitable maintenance, preserving its image, data and other+credentials; a Docker restart alone does not apply a changed environment.++Configuration transfer includes API-token records, but **not server-side agent+inventory or enrolment state**, local login credentials or monitoring history.+It cannot change the primary URL saved on remote agents. If the address changes,+follow [agent retargeting](UNIFIED_AGENT.md#moving-pulse-to-a-new-address),+preserving each agent's identity, credential and TLS trust. Verify fresh admission+and ordinary reports before retiring the source; imported records alone do not+establish agent recovery.### Developer/Test Overrides (Environment Variables)diff --git a/frontend-modern/public/docs/MIGRATION.md b/frontend-modern/public/docs/MIGRATION.mdindex 8343f97b89..eb0c8e1fc4 100644--- a/frontend-modern/public/docs/MIGRATION.md+++ b/frontend-modern/public/docs/MIGRATION.md@@ -33,6 +33,12 @@ settings included above. Imported API-token records retain their scopes andexpiry; they do not reveal the original tokens or transfer every agent's state.SSO configuration **is included**, even though local login credentials are not.+Automated provisioning uses the same limited scope. Read the+[startup-import gate and safeguards](CONFIGURATION.md#auto-import-bootstrap)+before setting bootstrap variables: an existing installation without+`nodes.enc` is not protected by a first-run marker, and normal startup after+an import error does not confirm a successful transfer.+### Full-state recoveryIf you need the same installation's history and excluded state, retain adiff --git a/scripts/tests/test_bootstrap_import_docs.py b/scripts/tests/test_bootstrap_import_docs.pynew file mode 100644index 0000000000..58d8b93a1a--- /dev/null+++ b/scripts/tests/test_bootstrap_import_docs.py@@ -0,0 +1,94 @@+#!/usr/bin/env python3+"""Keep startup-import help from implying safe recovery of an existing server.++These are documentation controls, not native import or installed recovery proof.+The production gate/importer and the attempted runtime probe are retained with+the maintainer's outcome; no credential or service is used by these tests.+"""++from pathlib import Path+import re+import unittest+++ROOT = Path(__file__).resolve().parents[2]+++def bootstrap(text):+ return " ".join(text.split("### Auto-Import (Bootstrap)\n", 1)[1]+ .split("\n### ", 1)[0].split())+++class BootstrapImportDocsTest(unittest.TestCase):+ def guide(self):+ return bootstrap((ROOT / "docs/CONFIGURATION.md").read_text())++ def assert_gate_and_result(self, text):+ for boundary in ("`nodes.enc`", "`PULSE_DATA_DIR`", "file-presence check",+ "not a record of the first run", "Other existing settings",+ "do not prevent", "Do not delete `nodes.enc`",+ "not proof that import succeeded", "startup continues",+ "normal configuration loading", "can itself fail"):+ self.assertIn(boundary, text)+ self.assertNotIn("auto-imports on first start", text)++ def assert_transfer_scope(self, text):+ for boundary in ("MIGRATION.md#configuration-transfer", "not a full-state backup",+ "replaced, not merged", "SSO settings", "not server-side agent",+ "inventory or enrolment state", "local login credentials",+ "monitoring history", "identity, credential and TLS trust",+ "fresh admission", "ordinary reports", "before retiring the source"):+ self.assertIn(boundary, text)+ self.assertNotIn("import restores server-side agent credentials", text)++ def test_canonical_and_served_mirrors_agree(self):+ for name in ("CONFIGURATION.md", "MIGRATION.md"):+ self.assertEqual((ROOT / "docs" / name).read_bytes(),+ (ROOT / "frontend-modern/public/docs" / name).read_bytes())++ def test_gate_is_not_a_first_run_or_success_guarantee(self):+ self.assert_gate_and_result(self.guide())++ def test_scope_preserves_agent_access_and_excluded_state(self):+ self.assert_transfer_scope(self.guide())++ def test_input_precedence_and_private_provisioning_are_explicit(self):+ text = self.guide()+ for boundary in ("takes precedence over `PULSE_INIT_CONFIG_DATA`",+ "does **not** fall back", "not supported by server startup",+ "owner-only", "private credential source", "separate from the backup",+ "command arguments, URLs, shared Compose files, logs or issue reports",+ "base64 is not redaction", "no passphrase-file variable",+ "authenticated Recovery form"):+ self.assertIn(boundary, text)+ self.assertNotRegex(text, r"PULSE_INIT_CONFIG_(?:PASSPHRASE_FILE|FORCE)")+ self.assertNotRegex(text, r"```(?:bash|sh|shell|yaml|dotenv)\b")++ def test_cutover_and_retry_boundaries_are_usable_without_a_reset(self):+ text = self.guide()+ for boundary in ("isolated destination", "private backup of the destination",+ "Isolate the trial destination from agents and notification",+ "activate monitoring and delivery", "one active installation",+ "independent outage coverage", "stop the trial destination",+ "reconcile its state before another attempt", "Do not repeat import",+ "replay notifications", "remove only the three",+ "deployment's managed source", "Docker restart alone does not apply"):+ self.assertIn(boundary, text)+ migration = (ROOT / "docs/MIGRATION.md").read_text()+ self.assertIn("CONFIGURATION.md#auto-import-bootstrap", migration)++ def test_discriminates_the_unsafe_promises(self):+ # Removing either boundary restores a real misleading interpretation.+ text = self.guide()+ for changed in (+ text.replace("not a record of the first run", "a record of the first run"),+ text.replace("not proof that import succeeded", "proof that import succeeded"),+ ):+ with self.assertRaises(AssertionError):+ self.assert_gate_and_result(changed)+ with self.assertRaises(AssertionError):+ self.assert_transfer_scope(text.replace("replaced, not merged", "merged"))+++if __name__ == "__main__":+ unittest.main()