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.

Keep manual server installation help on the hardened path

pulse-triage[bot]a6959e571ba0
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 70e326c93e..0e7a9adb2d 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -193,40 +193,43 @@ sudo bash install.sh --version "${PULSE_VERSION}"
> **Note**: This installs the Pulse server. Use the `/install.sh` endpoint from **Settings → Infrastructure → Install on a host** for installing or upgrading `pulse-agent` on monitored hosts.
<details>
-<summary><strong>Manual systemd install (advanced)</strong></summary>
+<summary><strong>Manual or custom systemd services (advanced)</strong></summary>
+
+For a **new Pulse server**, use the signed installer above rather than copying
+one binary and writing a minimal service unit. The installer creates the
+`pulse` service account, prepares the release tree and data ownership, and
+installs the server service and update assets together. Its server unit uses
+`User=pulse`, `Group=pulse`, `NoNewPrivileges=true`, `PrivateTmp=true`,
+`ProtectSystem=strict` and `ProtectHome=true`, with writes limited to the
+installation and data directories. Pulse's server does not need a root service;
+the separate host **agent** has different privilege requirements (see
+[Agent Security](AGENT_SECURITY.md)).
+
+For an **existing manual or custom installation**, first inspect its effective
+service settings locally. This read-only command does not print environment
+values or credentials:
```bash
-# Download and extract the architecture-specific tarball from GitHub Releases:
-# https://github.com/rcourtman/Pulse/releases
-# e.g.
-# curl -fsSLO "https://github.com/rcourtman/Pulse/releases/download/${PULSE_VERSION}/pulse-${PULSE_VERSION}-linux-amd64.tar.gz"
-# tar -xzf "pulse-${PULSE_VERSION}-linux-amd64.tar.gz"
-# The extracted tree contains ./bin/pulse plus ./bin/pulse-agent-* and ./scripts/.
-
-sudo install -m 0755 bin/pulse /usr/local/bin/pulse
-
-# Create systemd service
-sudo tee /etc/systemd/system/pulse.service > /dev/null << 'EOF'
-[Unit]
-Description=Pulse Monitoring
-After=network.target
-
-[Service]
-Type=simple
-ExecStart=/usr/local/bin/pulse
-Restart=always
-RestartSec=10
-Environment=PULSE_DATA_DIR=/etc/pulse
-
-[Install]
-WantedBy=multi-user.target
-EOF
-
-# Start service
-sudo mkdir -p /etc/pulse
-sudo systemctl daemon-reload
-sudo systemctl enable --now pulse
+systemctl show pulse.service \
+ --property=User --property=Group --property=NoNewPrivileges \
+ --property=PrivateTmp --property=ProtectSystem --property=ProtectHome
```
+
+Use your actual server unit name if it differs; older installations may use
+`pulse-backend.service`. An empty `User=` means systemd runs the service as
+root. Missing hardening is not repaired just by downloading a new binary:
+**the installer preserves existing service units during updates**, including
+custom units.
+
+Do not overwrite a working unit, change only its service user, or reinstall over
+an existing data directory to match these settings. Before a migration, follow
+[the recovery guide](RECOVERY.md), preserve the data directory and its encryption
+key, and record the active data path and deployment-managed configuration
+privately. Check that the intended service account can access that state and
+that required integrations work with the chosen sandbox. Do not loosen data
+permissions, remove authentication or share a full unit/environment dump as a
+shortcut.
+
</details>
---
diff --git a/frontend-modern/browser-tests/docs-fragment-navigation.tsx b/frontend-modern/browser-tests/docs-fragment-navigation.tsx
index 2c125f2a3b..b7e8976db6 100644
--- a/frontend-modern/browser-tests/docs-fragment-navigation.tsx
+++ b/frontend-modern/browser-tests/docs-fragment-navigation.tsx
@@ -23,6 +23,7 @@ const targets: Record<string, string> = {
missing: '/docs/API#does-not-exist',
troubleshooting: '/docs/TROUBLESHOOTING#recovery-mode',
truenas: '/docs/TRUENAS',
+ installation: '/docs/INSTALL',
};
window.history.replaceState({}, '', targets[scenario] ?? targets.plain);
diff --git a/frontend-modern/browser-tests/systemd-install-help.cjs b/frontend-modern/browser-tests/systemd-install-help.cjs
new file mode 100644
index 0000000000..bf9592a683
--- /dev/null
+++ b/frontend-modern/browser-tests/systemd-install-help.cjs
@@ -0,0 +1,100 @@
+// Exercise the real Docs renderer/router/styles and shipped installation guide.
+// This is help verification, not an installed service migration or upgrade.
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { chromium, webkit } = require('playwright');
+
+(async () => {
+ const root = '/workspace/frontend-modern';
+ const artifacts = path.join(root, 'node_modules', 'systemd-install-help-browser');
+ fs.mkdirSync(artifacts, { recursive: true });
+ const { createServer } = await import(path.join(root, 'node_modules/vite/dist/node/index.js'));
+ const server = await createServer({
+ root,
+ configFile: path.join(root, 'vite.config.ts'),
+ cacheDir: path.join(root, 'node_modules', '.vite-systemd-install-help'),
+ server: { host: '127.0.0.1', port: 5251, strictPort: true },
+ optimizeDeps: { noDiscovery: true, include: [] },
+ });
+ const results = [];
+ let browser;
+ try {
+ await server.listen();
+ for (const [engine, width] of [['chromium', 1280], ['webkit', 390]]) {
+ browser = await { chromium, webkit }[engine].launch(engine === 'chromium'
+ ? { headless: true, channel: 'chromium', args: ['--no-sandbox'] }
+ : { headless: true });
+ const page = await browser.newPage({ viewport: { width, height: 1000 },
+ ...(engine === 'webkit' ? { isMobile: true, hasTouch: true } : {}) });
+ const errors = [];
+ page.on('pageerror', (error) => errors.push(error.message));
+ page.on('console', (message) => {
+ if (message.type() === 'error') errors.push(message.text());
+ });
+ await page.goto('http://127.0.0.1:5251/browser-tests/docs-fragment-navigation.html?scenario=installation',
+ { waitUntil: 'domcontentloaded', timeout: 60_000 });
+ const summary = page.locator('summary').filter({
+ hasText: 'Manual or custom systemd services (advanced)',
+ });
+ await summary.waitFor();
+ if (engine === 'webkit') {
+ await page.evaluate(async () => {
+ document.documentElement.classList.add('dark');
+ await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+ await Promise.all(document.getAnimations().map((animation) => animation.finished.catch(() => {})));
+ });
+ }
+ const details = summary.locator('..');
+ assert.equal(await details.getAttribute('open'), null);
+ await summary.focus();
+ await page.keyboard.press('Enter');
+ assert.notEqual(await details.getAttribute('open'), null);
+ const content = await details.innerText();
+ for (const text of ['use the signed installer above', 'User=pulse', 'Group=pulse',
+ 'NoNewPrivileges=true', 'ProtectSystem=strict', 'An empty User= means',
+ 'the installer preserves existing service units during updates',
+ 'Do not overwrite a working unit, change only its service user',
+ 'preserve the data directory and its encryption key',
+ 'separate host agent has different privilege requirements'])
+ assert.ok(content.includes(text), text);
+ const command = await details.locator('pre').innerText();
+ assert.ok(command.startsWith('systemctl show pulse.service'));
+ assert.ok(!/--property=(Environment|ExecStart)|sudo|tee|install -m/.test(command));
+ assert.ok(!await page.locator('article').innerText().then((text) =>
+ text.includes('sudo tee /etc/systemd/system/pulse.service')));
+ await summary.evaluate((element) => element.scrollIntoView({ block: 'start' }));
+ await page.screenshot({ path: path.join(artifacts, `${engine}-account.png`) });
+ await details.locator('pre').evaluate((element) => element.scrollIntoView({ block: 'start' }));
+ await page.screenshot({ path: path.join(artifacts, `${engine}-checks.png`) });
+ assert.ok(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth + 1));
+ const recovery = details.getByRole('link', { name: 'the recovery guide', exact: true });
+ assert.equal(await recovery.getAttribute('href'), '/docs/RECOVERY');
+ await recovery.focus();
+ await page.keyboard.press('Enter');
+ await page.waitForURL('**/docs/RECOVERY');
+ await page.getByRole('heading', { level: 1 }).filter({ hasText: 'Recovery' }).waitFor();
+ assert.deepEqual(errors, []);
+ results.push({ engine, version: browser.version(), width,
+ keyboardDisclosure: true, nonRootServer: true, agentBoundary: true,
+ readOnlyCredentialSafeCommand: true, preservationWarning: true,
+ noDocumentOverflow: true, keyboardRecoveryLink: true, errors });
+ await browser.close();
+ browser = undefined;
+ }
+ const files = ['public/docs/INSTALL.md', 'browser-tests/systemd-install-help.cjs',
+ 'browser-tests/docs-fragment-navigation.tsx', 'src/features/docs/docMarkdown.ts',
+ 'src/pages/Docs.tsx'].map((file) => ({ file,
+ sha256: crypto.createHash('sha256').update(fs.readFileSync(path.join(root, file))).digest('hex') }));
+ const result = { result: 'passed', playwright: require('playwright/package.json').version,
+ scope: 'existing shipped installation-help rendering and navigation, not installed/systemd acceptance',
+ dompurify: JSON.parse(fs.readFileSync(path.join(root, 'node_modules/dompurify/package.json'))).version,
+ files, results };
+ fs.writeFileSync(path.join(artifacts, 'result.json'), JSON.stringify(result, null, 2) + '\n');
+ console.log(JSON.stringify(result));
+ } finally {
+ if (browser) await browser.close();
+ await server.close();
+ }
+})().catch((error) => { console.error(error); process.exitCode = 1; });
diff --git a/frontend-modern/public/docs/INSTALL.md b/frontend-modern/public/docs/INSTALL.md
index 70e326c93e..0e7a9adb2d 100644
--- a/frontend-modern/public/docs/INSTALL.md
+++ b/frontend-modern/public/docs/INSTALL.md
@@ -193,40 +193,43 @@ sudo bash install.sh --version "${PULSE_VERSION}"
> **Note**: This installs the Pulse server. Use the `/install.sh` endpoint from **Settings → Infrastructure → Install on a host** for installing or upgrading `pulse-agent` on monitored hosts.
<details>
-<summary><strong>Manual systemd install (advanced)</strong></summary>
+<summary><strong>Manual or custom systemd services (advanced)</strong></summary>
+
+For a **new Pulse server**, use the signed installer above rather than copying
+one binary and writing a minimal service unit. The installer creates the
+`pulse` service account, prepares the release tree and data ownership, and
+installs the server service and update assets together. Its server unit uses
+`User=pulse`, `Group=pulse`, `NoNewPrivileges=true`, `PrivateTmp=true`,
+`ProtectSystem=strict` and `ProtectHome=true`, with writes limited to the
+installation and data directories. Pulse's server does not need a root service;
+the separate host **agent** has different privilege requirements (see
+[Agent Security](AGENT_SECURITY.md)).
+
+For an **existing manual or custom installation**, first inspect its effective
+service settings locally. This read-only command does not print environment
+values or credentials:
```bash
-# Download and extract the architecture-specific tarball from GitHub Releases:
-# https://github.com/rcourtman/Pulse/releases
-# e.g.
-# curl -fsSLO "https://github.com/rcourtman/Pulse/releases/download/${PULSE_VERSION}/pulse-${PULSE_VERSION}-linux-amd64.tar.gz"
-# tar -xzf "pulse-${PULSE_VERSION}-linux-amd64.tar.gz"
-# The extracted tree contains ./bin/pulse plus ./bin/pulse-agent-* and ./scripts/.
-
-sudo install -m 0755 bin/pulse /usr/local/bin/pulse
-
-# Create systemd service
-sudo tee /etc/systemd/system/pulse.service > /dev/null << 'EOF'
-[Unit]
-Description=Pulse Monitoring
-After=network.target
-
-[Service]
-Type=simple
-ExecStart=/usr/local/bin/pulse
-Restart=always
-RestartSec=10
-Environment=PULSE_DATA_DIR=/etc/pulse
-
-[Install]
-WantedBy=multi-user.target
-EOF
-
-# Start service
-sudo mkdir -p /etc/pulse
-sudo systemctl daemon-reload
-sudo systemctl enable --now pulse
+systemctl show pulse.service \
+ --property=User --property=Group --property=NoNewPrivileges \
+ --property=PrivateTmp --property=ProtectSystem --property=ProtectHome
```
+
+Use your actual server unit name if it differs; older installations may use
+`pulse-backend.service`. An empty `User=` means systemd runs the service as
+root. Missing hardening is not repaired just by downloading a new binary:
+**the installer preserves existing service units during updates**, including
+custom units.
+
+Do not overwrite a working unit, change only its service user, or reinstall over
+an existing data directory to match these settings. Before a migration, follow
+[the recovery guide](RECOVERY.md), preserve the data directory and its encryption
+key, and record the active data path and deployment-managed configuration
+privately. Check that the intended service account can access that state and
+that required integrations work with the chosen sandbox. Do not loosen data
+permissions, remove authentication or share a full unit/environment dump as a
+shortcut.
+
</details>
---
diff --git a/frontend-modern/src/utils/__tests__/docsLinks.test.ts b/frontend-modern/src/utils/__tests__/docsLinks.test.ts
index 69144e2f20..255b77334b 100644
--- a/frontend-modern/src/utils/__tests__/docsLinks.test.ts
+++ b/frontend-modern/src/utils/__tests__/docsLinks.test.ts
@@ -61,6 +61,27 @@ function getRuntimeSourceFiles(dir: string): string[] {
}
describe('docsLinks', () => {
+ it('keeps custom systemd server help on the signed non-root install path', () => {
+ const installation = readFileSync(path.join(repoRoot, 'docs', 'INSTALL.md'), 'utf8');
+ const custom = installation
+ .split('<summary><strong>Manual or custom systemd services (advanced)</strong></summary>')[1]
+ .split('</details>')[0];
+ expect(custom).toContain('use the signed installer above');
+ expect(custom).toContain('`User=pulse`, `Group=pulse`');
+ expect(custom).toContain('`ProtectSystem=strict` and `ProtectHome=true`');
+ expect(custom).toContain('An empty `User=` means');
+ expect(custom).toContain('the installer preserves existing service units during updates');
+ expect(custom).toContain('Do not overwrite a working unit, change only its service user');
+ expect(custom).toContain('preserve the data directory and its encryption');
+ expect(custom).toContain('separate host **agent** has different privilege requirements');
+ const commands = [...custom.matchAll(/```bash\n([\s\S]*?)```/g)].map((match) => match[1]);
+ expect(commands).toHaveLength(1);
+ expect(commands[0]).toContain('systemctl show pulse.service');
+ expect(commands[0]).not.toMatch(/--property=(Environment|ExecStart)|sudo|tee|install -m/);
+ expect(installation).not.toContain('sudo tee /etc/systemd/system/pulse.service');
+ expect(installation).not.toContain('ExecStart=/usr/local/bin/pulse');
+ });
+
it('keeps TrueNAS setup acceptance separate from a system-information probe', () => {
const truenas = readFileSync(path.join(repoRoot, 'docs', 'TRUENAS.md'), 'utf8');
const setup = truenas.split('## Quick Start')[1].split('## Creating a TrueNAS API Key')[0];