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 installer configuration snapshot scope before recovery
pulse-triage[bot]eae88139ff42
diff --git a/docs/AUTO_UPDATE.md b/docs/AUTO_UPDATE.mdindex 156e239b5a..316b5e9f53 100644--- a/docs/AUTO_UPDATE.md+++ b/docs/AUTO_UPDATE.md@@ -262,6 +262,51 @@ can omit SQLite sidecar files. Keep these backups private, not in an issue ordiagnostic attachment. See [configuration paths](CONFIGURATION.md) and[audit storage and safe recovery](AUDIT_LOGGING.md#storage).+### Installer configuration snapshots++The Linux installer and its updater helper make a different copy from the+in-app `backup-<timestamp>` snapshot above. **A configuration snapshot is not a+full-state backup, and Update History does not list or restore these installer+copies.** Check which updater ran and its original logs before choosing a copy.+Do not rerun an update or reinstall just to create or locate one.++The installer copies its effective `PULSE_CONFIG_DIR` (default `/etc/pulse`).+For the default paths, look privately in these locations:++| When the installer took the copy | Configuration snapshot location |+| --- | --- |+| The configuration directory's parent was writable | `/etc/pulse.backup.<timestamp>…/` |+| The parent was read-only, as in the hardened updater service | `/opt/pulse/config-backups/pulse.backup.<timestamp>…/` |++Custom service names and `PULSE_CONFIG_DIR` or `PULSE_INSTALL_DIR` overrides+change these paths. The timestamp suffix also varies by installer version;+use the effective paths and existing logs, not a guessed name. An in-app+`backup_path` is not the location of an installer copy.++The copy includes hidden entries and preserves symbolic links, **not the+contents of targets outside the copied tree**. A separately located runtime+data directory, metrics or audit store, or organisation directory is therefore+not automatically included. Nor does this configuration copy include the+server executable, service units or update helpers stored elsewhere. Retain+matching encryption and signing keys with the stores they protect; a copied+key without its data, or encrypted data without its key, is not recovery.++This is a file copy, not a consistent filesystem snapshot: Pulse may still be+writing while it is made. A database file's presence does not establish a+consistent database backup. Keep the copies private; they can contain secrets,+sessions and monitoring data, even if their names say only “configuration”.++The installer normally retains five completed copies for that configuration+name, ordered by their timestamped names, not by verified restore readiness.+An update that aborts before replacing files can remove the copy it just made.+Later runs can rotate older copies away, so these are not a durable archive.+An absent copy does not prove that the update completed or that data was lost.+Preserve the current state and original evidence; do not delete another+instance's snapshots, change retention or reset keys to make recovery fit.+Use the [stopped-service recovery procedure](#manual-rollback) and+[full-state recovery guidance](MIGRATION.md#full-state-recovery) to assess a+matching, consistent backup before restoring anything.+### Manual RollbackIf Pulse cannot start, work inside the Pulse host or LXC, not on the Proxmox hostdiff --git a/docs/INSTALL.md b/docs/INSTALL.mdindex c125dcc4f5..5084bcf62a 100644--- a/docs/INSTALL.md+++ b/docs/INSTALL.md@@ -401,7 +401,8 @@ not a full-state recovery tool, and a recorded backup path is not proof of acomplete backup.Check the [version-specific snapshot scope](AUTO_UPDATE.md#what-an-update-snapshot-contains)-and use the [stopped-service recovery procedure](AUTO_UPDATE.md#manual-rollback)+and the separate [installer configuration snapshots](AUTO_UPDATE.md#installer-configuration-snapshots).+Use the [stopped-service recovery procedure](AUTO_UPDATE.md#manual-rollback)when data needs restoring. Keep matching data and keys together, verify thebackup privately and preserve reversible copies of the failed state. Do notreplace live runtime data or delete it to make a rollback fit.diff --git a/frontend-modern/public/docs/AUTO_UPDATE.md b/frontend-modern/public/docs/AUTO_UPDATE.mdindex 156e239b5a..316b5e9f53 100644--- a/frontend-modern/public/docs/AUTO_UPDATE.md+++ b/frontend-modern/public/docs/AUTO_UPDATE.md@@ -262,6 +262,51 @@ can omit SQLite sidecar files. Keep these backups private, not in an issue ordiagnostic attachment. See [configuration paths](CONFIGURATION.md) and[audit storage and safe recovery](AUDIT_LOGGING.md#storage).+### Installer configuration snapshots++The Linux installer and its updater helper make a different copy from the+in-app `backup-<timestamp>` snapshot above. **A configuration snapshot is not a+full-state backup, and Update History does not list or restore these installer+copies.** Check which updater ran and its original logs before choosing a copy.+Do not rerun an update or reinstall just to create or locate one.++The installer copies its effective `PULSE_CONFIG_DIR` (default `/etc/pulse`).+For the default paths, look privately in these locations:++| When the installer took the copy | Configuration snapshot location |+| --- | --- |+| The configuration directory's parent was writable | `/etc/pulse.backup.<timestamp>…/` |+| The parent was read-only, as in the hardened updater service | `/opt/pulse/config-backups/pulse.backup.<timestamp>…/` |++Custom service names and `PULSE_CONFIG_DIR` or `PULSE_INSTALL_DIR` overrides+change these paths. The timestamp suffix also varies by installer version;+use the effective paths and existing logs, not a guessed name. An in-app+`backup_path` is not the location of an installer copy.++The copy includes hidden entries and preserves symbolic links, **not the+contents of targets outside the copied tree**. A separately located runtime+data directory, metrics or audit store, or organisation directory is therefore+not automatically included. Nor does this configuration copy include the+server executable, service units or update helpers stored elsewhere. Retain+matching encryption and signing keys with the stores they protect; a copied+key without its data, or encrypted data without its key, is not recovery.++This is a file copy, not a consistent filesystem snapshot: Pulse may still be+writing while it is made. A database file's presence does not establish a+consistent database backup. Keep the copies private; they can contain secrets,+sessions and monitoring data, even if their names say only “configuration”.++The installer normally retains five completed copies for that configuration+name, ordered by their timestamped names, not by verified restore readiness.+An update that aborts before replacing files can remove the copy it just made.+Later runs can rotate older copies away, so these are not a durable archive.+An absent copy does not prove that the update completed or that data was lost.+Preserve the current state and original evidence; do not delete another+instance's snapshots, change retention or reset keys to make recovery fit.+Use the [stopped-service recovery procedure](#manual-rollback) and+[full-state recovery guidance](MIGRATION.md#full-state-recovery) to assess a+matching, consistent backup before restoring anything.+### Manual RollbackIf Pulse cannot start, work inside the Pulse host or LXC, not on the Proxmox hostdiff --git a/frontend-modern/public/docs/INSTALL.md b/frontend-modern/public/docs/INSTALL.mdindex c125dcc4f5..5084bcf62a 100644--- a/frontend-modern/public/docs/INSTALL.md+++ b/frontend-modern/public/docs/INSTALL.md@@ -401,7 +401,8 @@ not a full-state recovery tool, and a recorded backup path is not proof of acomplete backup.Check the [version-specific snapshot scope](AUTO_UPDATE.md#what-an-update-snapshot-contains)-and use the [stopped-service recovery procedure](AUTO_UPDATE.md#manual-rollback)+and the separate [installer configuration snapshots](AUTO_UPDATE.md#installer-configuration-snapshots).+Use the [stopped-service recovery procedure](AUTO_UPDATE.md#manual-rollback)when data needs restoring. Keep matching data and keys together, verify thebackup privately and preserve reversible copies of the failed state. Do notreplace live runtime data or delete it to make a rollback fit.diff --git a/frontend-modern/src/features/docs/__tests__/installerSnapshotGuide.test.ts b/frontend-modern/src/features/docs/__tests__/installerSnapshotGuide.test.tsnew file mode 100644index 0000000000..c499fc1138--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/installerSnapshotGuide.test.ts@@ -0,0 +1,82 @@+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { describe, expect, it } from 'vitest';+import { renderDocMarkdown } from '../docMarkdown';++const read = (file: string) => readFileSync(path.resolve(process.cwd(), '..', file), 'utf8');+const article = (name: string) => {+ const result = document.createElement('article');+ result.innerHTML = renderDocMarkdown(read(`docs/${name}.md`), name);+ return result;+};+const section = () => {+ const heading = article('AUTO_UPDATE').querySelector('#installer-configuration-snapshots');+ expect(heading).not.toBeNull();+ const result = document.createElement('section');+ for (+ let node = heading!.nextElementSibling;+ node && node.tagName !== 'H3' && node.tagName !== 'H2';+ node = node.nextElementSibling+ ) {+ result.appendChild(node.cloneNode(true));+ }+ return result;+};+const text = () => section().textContent!.replace(/\s+/g, ' ');++describe('installer configuration snapshot guidance', () => {+ it('keeps the two default locations literal and distinct from in-app snapshots', () => {+ const rows = [...section().querySelectorAll('tbody tr')];+ expect(rows.map((row) => row.querySelectorAll('td')[1].textContent)).toEqual([+ '/etc/pulse.backup.<timestamp>…/',+ '/opt/pulse/config-backups/pulse.backup.<timestamp>…/',+ ]);+ const installer = read('install.sh');+ expect(installer).toContain('backup_parent="$(dirname "$CONFIG_DIR")"');+ expect(installer).toContain('backup_parent="$INSTALL_DIR/config-backups"');+ expect(installer).toContain('local keep="${CONFIG_BACKUP_KEEP_COUNT:-5}"');+ expect(installer).toContain('cp -a -- "$CONFIG_DIR/."');+ expect(text()).toContain('normally retains five completed copies');+ expect(text()).toContain('Custom service names');+ expect(text()).toContain('Update History does not list or restore these installer copies');+ expect(text()).toContain('An in-app backup_path is not the location of an installer copy');+ });++ it('does not turn a rotating file copy into complete, consistent or automatic recovery', () => {+ for (const distinction of [+ 'not a full-state backup',+ 'not the contents of targets outside the copied tree',+ 'not automatically included',+ 'server executable, service units or update helpers stored elsewhere',+ 'Pulse may still be writing',+ 'not a durable archive',+ 'does not prove that the update completed or that data was lost',+ 'Do not rerun an update or reinstall',+ 'Keep the copies private',+ 'do not delete another instance',+ 'reset keys to make recovery fit',+ ]) {+ expect(text()).toContain(distinction);+ }+ expect(section().querySelector('pre')).toBeNull();+ });++ it('reaches real shipped recovery sections from the existing installation guide', () => {+ expect(+ article('INSTALL').querySelector(+ 'a[href="/docs/AUTO_UPDATE#installer-configuration-snapshots"]',+ ),+ ).not.toBeNull();+ for (const [name, fragment] of [+ ['AUTO_UPDATE', 'manual-rollback'],+ ['MIGRATION', 'full-state-recovery'],+ ]) {+ const href = name === 'AUTO_UPDATE' ? `#${fragment}` : `/docs/${name}#${fragment}`;+ expect(section().querySelector(`a[href="${href}"]`)).not.toBeNull();+ expect(article(name).querySelector(`#${fragment}`)).not.toBeNull();+ }+ for (const name of ['INSTALL', 'AUTO_UPDATE']) {+ expect(read(`frontend-modern/public/docs/${name}.md`)).toBe(read(`docs/${name}.md`));+ }+ });+});