Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

Explain startup import without promising safe first-run recovery

pulse-triage[bot]9c1b4ef8ddb9
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 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.md
index 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 and
expiry; 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 recovery
If you need the same installation's history and excluded state, retain a
diff --git a/frontend-modern/public/docs/CONFIGURATION.md b/frontend-modern/public/docs/CONFIGURATION.md
index 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.md
index 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 and
expiry; 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 recovery
If you need the same installation's history and excluded state, retain a
diff --git a/scripts/tests/test_bootstrap_import_docs.py b/scripts/tests/test_bootstrap_import_docs.py
new file mode 100644
index 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()