-
Important: The backup contains node credentials but NOT
- authentication settings. Each Pulse instance should configure its own login
- credentials for security. Remember your{' '}
+
Configuration only: Includes Proxmox connections, SSO settings
+ and API-token records, but not history, TrueNAS/vSphere connections or agent
+ enrolment state. Local login credentials and sessions are not included. Check
+ the{' '}
+
+ migration guide
+ {' '}
+ before relying on this for recovery. Remember your{' '}
{props.useCustomPassphrase() || !props.securityStatus()?.hasAuthentication
? 'passphrase'
: 'password'}{' '}
@@ -282,13 +293,24 @@ export const BackupTransferDialogs: Component
= (pro
- Warning: Importing will replace all current configuration. This
- action cannot be undone.
+ Warning: Import replaces the included settings and API-token
+ records, not the whole installation. Back up the destination first. History and
+ excluded settings are not restored; check the{' '}
+
+ migration guide
+ {' '}
+ before retiring the old server.
- Agent migration: The backup restores server-side agent records
- and credentials, but it cannot change the Pulse URL stored on remote agents. If
- this server has a different address, retarget each agent after the import.
+ Agent migration: API-token records are included, but agent
+ inventory, enrolment state, profiles and assignments are not. Import cannot
+ change the Pulse URL stored on remote agents. Preserve each agent's identity and
+ private credential, retarget if the address changes, and verify fresh admission.
diff --git a/frontend-modern/src/components/Settings/__tests__/BackupTransferDialogs.test.tsx b/frontend-modern/src/components/Settings/__tests__/BackupTransferDialogs.test.tsx
index 1a0e2eb131..4820a58ea1 100644
--- a/frontend-modern/src/components/Settings/__tests__/BackupTransferDialogs.test.tsx
+++ b/frontend-modern/src/components/Settings/__tests__/BackupTransferDialogs.test.tsx
@@ -2,40 +2,65 @@ import { cleanup, render, screen } from '@solidjs/testing-library';
import { afterEach, describe, expect, it, vi } from 'vitest';
import { BackupTransferDialogs } from '../BackupTransferDialogs';
+function renderTransfer(kind: 'export' | 'import') {
+ return render(() => (
+ null}
+ exportPassphrase={() => ''}
+ setExportPassphrase={vi.fn()}
+ useCustomPassphrase={() => false}
+ setUseCustomPassphrase={vi.fn()}
+ importPassphrase={() => 'secure-passphrase'}
+ setImportPassphrase={vi.fn()}
+ importFile={() => null}
+ setImportFile={vi.fn()}
+ showExportDialog={() => kind === 'export'}
+ showImportDialog={() => kind === 'import'}
+ showApiTokenModal={() => false}
+ apiTokenInput={() => ''}
+ setApiTokenInput={vi.fn()}
+ handleExport={vi.fn()}
+ handleImport={vi.fn()}
+ closeExportDialog={vi.fn()}
+ closeImportDialog={vi.fn()}
+ closeApiTokenModal={vi.fn()}
+ handleApiTokenAuthenticate={vi.fn()}
+ />
+ ));
+}
+
describe('BackupTransferDialogs', () => {
- afterEach(() => {
- cleanup();
+ afterEach(cleanup);
+
+ it('discloses the actual archive scope before exporting', () => {
+ renderTransfer('export');
+ expect(screen.getByText('Configuration only:')).toBeInTheDocument();
+ const text = screen.getByRole('dialog', { name: 'Export configuration' }).textContent;
+ expect(text).toContain('SSO settings');
+ expect(text).toContain('API-token records');
+ expect(text).toContain('not history, TrueNAS/vSphere connections');
+ expect(text).toContain('Local login credentials and sessions are not included');
+ expect(text).not.toContain('NOT authentication settings');
+ expect(screen.getByRole('link', { name: 'migration guide' })).toHaveAttribute(
+ 'href',
+ '/docs/MIGRATION',
+ );
});
- it('discloses that configuration import cannot retarget remote agents', () => {
- render(() => (
- null}
- exportPassphrase={() => ''}
- setExportPassphrase={vi.fn()}
- useCustomPassphrase={() => false}
- setUseCustomPassphrase={vi.fn()}
- importPassphrase={() => 'secure-passphrase'}
- setImportPassphrase={vi.fn()}
- importFile={() => null}
- setImportFile={vi.fn()}
- showExportDialog={() => false}
- showImportDialog={() => true}
- showApiTokenModal={() => false}
- apiTokenInput={() => ''}
- setApiTokenInput={vi.fn()}
- handleExport={vi.fn()}
- handleImport={vi.fn()}
- closeExportDialog={vi.fn()}
- closeImportDialog={vi.fn()}
- closeApiTokenModal={vi.fn()}
- handleApiTokenAuthenticate={vi.fn()}
- />
- ));
-
+ it('distinguishes token transfer from agent admission before importing', () => {
+ renderTransfer('import');
expect(screen.getByText('Agent migration:')).toBeInTheDocument();
- expect(
- screen.getByText(/it cannot change the Pulse URL stored on remote agents/i),
- ).toBeInTheDocument();
+ const text = screen.getByRole('dialog', { name: 'Import configuration' }).textContent;
+ expect(text).toContain('Back up the destination first');
+ expect(text).toContain('not the whole installation');
+ expect(text).toContain('inventory, enrolment state, profiles and assignments are not');
+ expect(text).toContain('Import cannot change the Pulse URL stored on remote agents');
+ expect(text).toContain('Preserve each agent');
+ expect(text).toContain('verify fresh admission');
+ expect(text).not.toContain('restores server-side agent records');
+ const guide = screen.getByRole('link', { name: 'migration guide' });
+ expect(guide).toHaveAttribute('href', '/docs/MIGRATION');
+ expect(guide).toHaveAttribute('target', '_blank');
+ expect(guide).toHaveAttribute('rel', 'noopener noreferrer');
});
});
diff --git a/frontend-modern/src/utils/__tests__/docsLinks.test.ts b/frontend-modern/src/utils/__tests__/docsLinks.test.ts
index d4bac377ae..0d980ec443 100644
--- a/frontend-modern/src/utils/__tests__/docsLinks.test.ts
+++ b/frontend-modern/src/utils/__tests__/docsLinks.test.ts
@@ -131,6 +131,31 @@ describe('docsLinks', () => {
}
});
+ it('keeps configuration transfer separate from full-state recovery', () => {
+ const migration = readFileSync(path.join(repoRoot, 'docs', 'MIGRATION.md'), 'utf8');
+ const agent = readFileSync(path.join(repoRoot, 'docs', 'UNIFIED_AGENT.md'), 'utf8');
+ const scope = migration
+ .split('### Configuration transfer')[1]
+ .split('### Full-state recovery')[0];
+ expect(scope).toContain('Proxmox VE, PBS and PMG');
+ expect(scope).toContain('| TrueNAS, vSphere and Machine Availability');
+ expect(scope).toContain('SSO configuration **is included**');
+ expect(scope).toContain(
+ 'Server-side host/Docker/Kubernetes agent inventory and enrolment state',
+ );
+ expect(migration).toContain('not a full backup of the installation');
+ expect(migration).toContain('Stop Pulse before taking that');
+ expect(migration).toContain('matching `.encryption.key`');
+ expect(migration).toContain('reload/apply failure');
+ expect(migration).toContain('it does not merge');
+ expect(migration).toContain('UNIFIED_AGENT.md#moving-pulse-to-a-new-address');
+ expect(migration).not.toContain('Update the `--token` flag');
+ expect(migration).not.toContain('Restored in < 5 minutes');
+ expect(migration).not.toContain('re-enable in Settings');
+ expect(agent).toContain('restores API-token records, not the server-side');
+ expect(agent).toContain('MIGRATION.md#configuration-transfer');
+ });
+
it('keeps lockout and incident reporting guidance safe for the affected client', () => {
const troubleshooting = readFileSync(path.join(repoRoot, 'docs', 'TROUBLESHOOTING.md'), 'utf8');
const recovery = troubleshooting.split('### Recovery Mode')[1].split('\n---')[0];
diff --git a/internal/config/migration_scope_test.go b/internal/config/migration_scope_test.go
new file mode 100644
index 0000000000..fc4b58377a
--- /dev/null
+++ b/internal/config/migration_scope_test.go
@@ -0,0 +1,118 @@
+package config
+
+import (
+ "bytes"
+ "encoding/base64"
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "testing"
+ "time"
+
+ "github.com/rcourtman/pulse-go-rewrite/pkg/auth"
+ "github.com/stretchr/testify/require"
+)
+
+// Exercise the actual archive, not a fabricated ExportData value: the migration
+// warnings must match what a fresh destination can recover with a different key.
+func TestConfigurationMigrationArchiveScope(t *testing.T) {
+ t.Setenv("PULSE_DATA_DIR", t.TempDir())
+ sourceDir, targetDir := t.TempDir(), t.TempDir()
+ source, target := NewConfigPersistence(sourceDir), NewConfigPersistence(targetDir)
+ require.NoError(t, source.EnsureConfigDir())
+ require.NoError(t, target.EnsureConfigDir())
+
+ nodes := []PVEInstance{{Name: "synthetic-pve", Host: "https://pve.example:8006", TokenName: "pulse@pve!read", TokenValue: "synthetic-node-secret"}}
+ require.NoError(t, source.SaveNodesConfig(nodes, nil, nil))
+ expires := time.Now().Add(time.Hour).UTC()
+ tokens := []APITokenRecord{{ID: "synthetic-agent-token", Name: "agent", Hash: auth.HashAPIToken("synthetic-agent-secret"), CreatedAt: time.Now().UTC(), ExpiresAt: &expires, Scopes: []string{ScopeAgentReport}, OrgID: "default"}}
+ require.NoError(t, source.SaveAPITokens(tokens))
+ sso := &SSOConfig{Providers: []SSOProvider{{ID: "synthetic-sso", Name: "SSO", Type: SSOProviderTypeOIDC, Enabled: true, OIDC: &OIDCProviderConfig{IssuerURL: "https://idp.example", ClientID: "synthetic", ClientSecret: "synthetic-sso-secret"}}}}
+ require.NoError(t, source.SaveSSOConfig(sso))
+ sourceNAS := []TrueNASInstance{{Name: "source-nas", Host: "https://nas.example", APIKey: "synthetic-nas-secret"}}
+ require.NoError(t, source.SaveTrueNASConfig(sourceNAS))
+ targetNAS := []TrueNASInstance{{Name: "target-nas", Host: "https://target.example", APIKey: "synthetic-target-secret"}}
+ require.NoError(t, target.SaveTrueNASConfig(targetNAS))
+
+ // Excluded state exists at both ends. Import must not pretend to transfer it
+ // or overwrite the destination's excluded files. These are inert sentinels,
+ // not live databases, credentials or operational agent records.
+ excluded := []string{".env", "metrics.db", "audit.db", "host_agents.json", "agent_profiles.json", "rbac_roles.json", "license.enc"}
+ for _, name := range excluded {
+ require.NoError(t, os.WriteFile(filepath.Join(sourceDir, name), []byte("synthetic-source-only"), 0600))
+ require.NoError(t, os.WriteFile(filepath.Join(targetDir, name), []byte("synthetic-destination-only"), 0600))
+ }
+ sourceKey, err := os.ReadFile(filepath.Join(sourceDir, ".encryption.key"))
+ require.NoError(t, err)
+ targetKey, err := os.ReadFile(filepath.Join(targetDir, ".encryption.key"))
+ require.NoError(t, err)
+ require.False(t, bytes.Equal(sourceKey, targetKey), "fresh destinations must use a different key")
+
+ const passphrase = "synthetic-migration-passphrase"
+ archive, err := source.ExportConfig(passphrase)
+ require.NoError(t, err)
+ ciphertext, err := base64.StdEncoding.DecodeString(archive)
+ require.NoError(t, err)
+ plaintext, err := decryptWithPassphrase(ciphertext, passphrase)
+ require.NoError(t, err)
+ var payload map[string]json.RawMessage
+ require.NoError(t, json.Unmarshal(plaintext, &payload))
+ require.Equal(t, "4.4", stringValue(t, payload["version"]))
+ // Changing archive scope requires updating the actual user-facing account,
+ // not silently assuming every persisted store is in a configuration export.
+ require.ElementsMatch(t, []string{"version", "exportedAt", "nodes", "alerts", "alertIntentPolicies", "email", "webhooks", "apprise", "deadMan", "system", "sso", "apiTokens"}, rawKeys(payload))
+ require.NotContains(t, string(plaintext), "synthetic-nas-secret")
+ require.NotContains(t, string(plaintext), "synthetic-source-only")
+ require.Contains(t, string(plaintext), "synthetic-sso-secret")
+
+ baseline := []PVEInstance{{Name: "destination-before", Host: "https://before.example:8006"}}
+ require.NoError(t, target.SaveNodesConfig(baseline, nil, nil))
+ require.Error(t, target.ImportConfig(archive, "wrong-synthetic-passphrase"))
+ unchanged, err := target.LoadNodesConfig()
+ require.NoError(t, err)
+ require.Equal(t, baseline[0].Name, unchanged.PVEInstances[0].Name)
+
+ require.NoError(t, target.ImportConfig(archive, passphrase))
+ reopened := NewConfigPersistence(targetDir)
+ restored, err := reopened.LoadNodesConfig()
+ require.NoError(t, err)
+ require.Equal(t, nodes[0].TokenValue, restored.PVEInstances[0].TokenValue)
+ require.Equal(t, nodes[0].Name, restored.PVEInstances[0].Name)
+ restoredSSO, err := reopened.LoadSSOConfig()
+ require.NoError(t, err)
+ require.Equal(t, sso.Providers[0].OIDC.ClientSecret, restoredSSO.Providers[0].OIDC.ClientSecret)
+ restoredTokens, err := reopened.LoadAPITokens()
+ require.NoError(t, err)
+ cfg := &Config{APITokens: restoredTokens}
+ record, ok := cfg.ValidateAPIToken("synthetic-agent-secret")
+ require.True(t, ok, "restored records validate the existing credential without replacing it")
+ require.Equal(t, tokens[0].ID, record.ID)
+ require.Equal(t, tokens[0].Scopes, record.Scopes)
+ require.WithinDuration(t, expires, *record.ExpiresAt, time.Millisecond)
+ nas, err := reopened.LoadTrueNASConfig()
+ require.NoError(t, err)
+ require.Equal(t, targetNAS[0].Name, nas[0].Name)
+ for _, name := range excluded {
+ data, err := os.ReadFile(filepath.Join(targetDir, name))
+ require.NoError(t, err)
+ require.Equal(t, "synthetic-destination-only", string(data), name)
+ }
+ keyAfter, err := os.ReadFile(filepath.Join(targetDir, ".encryption.key"))
+ require.NoError(t, err)
+ require.True(t, bytes.Equal(targetKey, keyAfter), "configuration import keeps the destination key")
+}
+
+func rawKeys(payload map[string]json.RawMessage) []string {
+ keys := make([]string, 0, len(payload))
+ for key := range payload {
+ keys = append(keys, key)
+ }
+ return keys
+}
+
+func stringValue(t *testing.T, raw json.RawMessage) string {
+ t.Helper()
+ var value string
+ require.NoError(t, json.Unmarshal(raw, &value))
+ return value
+}