Update documentation with configuration and deployment details

- CONFIGURATION.md: Add comprehensive system.json keys table with descriptions for all polling, discovery, and UI settings - DEPLOYMENT_MODELS.md: Document audit signing key, agent profile files, org metadata, and multi-tenant storage layout - METRICS_HISTORY.md: Update resourceType values, add maxPoints param, document Pro license requirement for ranges beyond 7d - MULTI_TENANT.md: Add storage layout and migration section, remove completed TODO items from backlog - CENTRALIZED_MANAGEMENT.md: Update links and clarify architecture - API.md: Update endpoint documentation - UNIFIED_AGENT.md: Document --version and --self-test flags
2026-02-18 00:17:39 +01:00 · 2026-02-01 22:24:48 +00:00
parent 6d33733c56
commit ec802c4864
7 changed files with 197 additions and 15 deletions
--- a/docs/API.md
+++ b/docs/API.md
@@ -208,8 +208,8 @@ Triggers a test alert to all configured channels.
 - `POST /api/admin/webhooks/audit` (admin, `settings:write`)

 ### Advanced Reporting (Pro)
- `GET /api/admin/reports/generate` (admin, `node:read`)
-  - Query params: `format` (pdf/csv), `id` (resource ID), `type` (node/vm/container/storage), `metric` (cpu/mem/avg), `range` (1h/24h/7d)
+- `GET /api/admin/reports/generate` (admin, `settings:read`)
+  - Query params: `format` (pdf/csv, default `pdf`), `resourceType`, `resourceId`, `metricType` (optional), `start`/`end` (RFC3339, optional; defaults to last 24h), `title` (optional)

 ### Queue and Dead-Letter Tools
 - `GET /api/notifications/queue/stats` (admin)
@@ -541,10 +541,13 @@ Returns stats for the persistent metrics store (SQLite-backed).
 Returns historical metric series for a resource and time range.

 Query params:
- `resourceType` (required): `node`, `vm`, `container`, `storage`, `dockerHost`, `dockerContainer`
+- `resourceType` (required): `node`, `guest` (VM/LXC), `storage`, `docker`, `dockerHost`
 - `resourceId` (required)
 - `metric` (optional): `cpu`, `memory`, `disk`, etc. Omit for all metrics
- `range` (optional): `1h`, `6h`, `12h`, `24h`, `7d`, `30d`, `90d` (default `24h`)
+- `range` (optional): `1h`, `6h`, `12h`, `24h`, `1d`, `7d`, `30d`, `90d` (default `24h`; duration strings also accepted)
+- `maxPoints` (optional): Downsample to a target number of points
+
+> **License**: Requests beyond `7d` require the Pulse Pro `long_term_metrics` feature. Unlicensed requests return `402 Payment Required`.

 ---

@@ -555,7 +558,7 @@ Query params:
 Downloads the unified agent binary. Without `arch`, Pulse serves the local binary on the server host.

 Optional query:
- `?arch=linux-amd64` (supported: `linux-amd64`, `linux-arm64`, `linux-armv7`, `linux-armv6`, `linux-386`, `darwin-amd64`, `darwin-arm64`, `windows-amd64`, `windows-arm64`, `windows-386`)
+- `?arch=linux-amd64` (supported: `linux-amd64`, `linux-arm64`, `linux-armv7`, `linux-armv6`, `linux-386`, `darwin-amd64`, `darwin-arm64`, `freebsd-amd64`, `freebsd-arm64`, `windows-amd64`, `windows-arm64`, `windows-386`)

 The response includes `X-Checksum-Sha256` for verification.

@@ -571,10 +574,20 @@ Returns the current server version for agent update checks.
 `GET /install.sh`
 Serves the universal `install.sh` used to install `pulse-agent` on target machines.

+`GET /api/install/install.sh`
+API-prefixed alias for the unified agent installer script.
+
 ### Unified Agent Installer (Windows)
 `GET /install.ps1`
 Serves the PowerShell installer for Windows.

+`GET /api/install/install.ps1`
+API-prefixed alias for the unified agent PowerShell installer.
+
+### Docker Server Installer Script
+`GET /api/install/install-docker.sh`
+Serves the turnkey Docker installer script that generates a `docker-compose.yml` and `.env`.
+
 ### Legacy Agents (Deprecated)
 `GET /download/pulse-host-agent` - *Deprecated, use pulse-agent*
 `GET /download/pulse-docker-agent` - *Deprecated, use pulse-agent --enable-docker*
@@ -619,8 +632,17 @@ Updates server-side config for an agent (e.g., `commandsEnabled`).
 ### Agent Profiles (Pro)
 `GET /api/admin/profiles` (admin, Pro)
 `POST /api/admin/profiles` (admin, Pro)
+`GET /api/admin/profiles/{id}` (admin, Pro)
 `PUT /api/admin/profiles/{id}` (admin, Pro)
 `DELETE /api/admin/profiles/{id}` (admin, Pro)
+`GET /api/admin/profiles/schema` (admin, Pro)
+`POST /api/admin/profiles/validate` (admin, Pro)
+`POST /api/admin/profiles/suggestions` (admin, Pro)
+`GET /api/admin/profiles/changelog` (admin, Pro)
+`GET /api/admin/profiles/deployments` (admin, Pro)
+`POST /api/admin/profiles/deployments` (admin, Pro)
+`GET /api/admin/profiles/{id}/versions` (admin, Pro)
+`POST /api/admin/profiles/{id}/rollback/{version}` (admin, Pro)
 `GET /api/admin/profiles/assignments` (admin, Pro)
 `POST /api/admin/profiles/assignments` (admin, Pro)
 `DELETE /api/admin/profiles/assignments/{agent_id}` (admin, Pro)
--- a/docs/CENTRALIZED_MANAGEMENT.md
+++ b/docs/CENTRALIZED_MANAGEMENT.md
@@ -16,16 +16,24 @@ The following settings can be controlled remotely via profiles:

 | Key | Type | Description |
 | :--- | :--- | :--- |
+| `interval` | string | Set reporting interval (e.g., "30s", "1m") |
+| `enable_host` | boolean | Enable/Disable host monitoring (metrics + command execution) |
 | `enable_docker` | boolean | Enable/Disable Docker monitoring |
 | `enable_kubernetes` | boolean | Enable/Disable Kubernetes monitoring |
 | `enable_proxmox` | boolean | Enable/Disable Proxmox monitoring |
-| `proxmox_type` | string | Set Proxmox type (`pve` or `pbs`) |
+| `proxmox_type` | string | Set Proxmox type (`pve`, `pbs`, or `auto`) |
+| `docker_runtime` | string | Container runtime preference (`auto`, `docker`, `podman`) |
+| `disable_auto_update` | boolean | Disable automatic agent updates |
+| `disable_docker_update_checks` | boolean | Disable Docker image update detection |
+| `kube_include_all_pods` | boolean | Include all non-succeeded pods in Kubernetes reports |
+| `kube_include_all_deployments` | boolean | Include all deployments in Kubernetes reports |
 | `log_level` | string | Set agent log level (`debug`, `info`, `warn`, `error`) |
-| `interval` | string | Set reporting interval (e.g., "30s", "1m") |
+| `report_ip` | string | Override the reported IP address for the agent |
+| `disable_ceph` | boolean | Disable local Ceph status polling |

 Notes:
 - `interval` accepts a duration string. If you send a JSON number, it is interpreted as seconds.
- Docker auto-detection can still enable Docker monitoring if the agent is not explicitly configured. To force-disable Docker, set `PULSE_ENABLE_DOCKER=false` or install with `--disable-docker` on the host.
+- Docker auto-detection can still enable Docker monitoring if the agent is not explicitly configured. To force-disable Docker, set `PULSE_ENABLE_DOCKER=false` or install with `--enable-docker=false` on the host.
 - `commandsEnabled` (AI command execution) is controlled separately per agent in **Settings → Agents → Unified Agents** and is applied live on report. It is not part of profile settings.

 ## API Usage
@@ -96,6 +104,76 @@ Authorization: Bearer <agent-or-admin-token>

 Requires `host-agent:config:read` (or admin tokens with management scopes).

+### 7. Schema, Validation, and Suggestions
+
+Use the schema endpoint to see supported keys and types, and validate configs before saving:
+
+```http
+GET /api/admin/profiles/schema
+Authorization: Bearer <admin-token>
+```
+
+```http
+POST /api/admin/profiles/validate
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+
+{
+  "config": {
+    "interval": "60s",
+    "enable_docker": true
+  }
+}
+```
+
+Optional AI suggestions:
+
+```http
+POST /api/admin/profiles/suggestions
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+```
+
+### 8. Version History and Rollback
+
+Each profile update increments its version and is stored in `profile-versions.json`.
+
+```http
+GET /api/admin/profiles/{id}/versions
+Authorization: Bearer <admin-token>
+```
+
+Rollback to a specific version:
+
+```http
+POST /api/admin/profiles/{id}/rollback/{version}
+Authorization: Bearer <admin-token>
+```
+
+### 9. Change Log and Deployment Status
+
+Change log entries are stored in `profile-changelog.json`:
+
+```http
+GET /api/admin/profiles/changelog
+Authorization: Bearer <admin-token>
+```
+
+Deployment status is stored in `profile-deployments.json`:
+
+```http
+GET /api/admin/profiles/deployments
+Authorization: Bearer <admin-token>
+```
+
+Update deployment status via:
+
+```http
+POST /api/admin/profiles/deployments
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+```
+
 ## Agent Behavior

 1.  On startup, the agent computes its Agent ID.
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -6,6 +6,7 @@ Pulse uses a split-configuration model to ensure security and flexibility.
 | ------ | --------- | ---------------- |
 | `.env` | Authentication & Secrets | 🔒 **Critical** (Read-only by owner) |
 | `.encryption.key` | Encryption key for `.enc` files | 🔒 **Critical** |
+| `.audit-signing.key` | Audit log signing key (Pulse Pro, encrypted) | 🔒 **Sensitive** |
 | `system.json` | General Settings | 📝 Standard |
 | `nodes.enc` | Node Credentials | 🔒 **Encrypted** (AES-256-GCM) |
 | `alerts.json` | Alert Rules | 📝 Standard |
@@ -25,6 +26,9 @@ Pulse uses a split-configuration model to ensure security and flexibility.
 | `guest_metadata.json` | Guest notes and metadata | 📝 Standard |
 | `agent_profiles.json` | Agent configuration profiles (Pulse Pro) | 📝 Standard |
 | `agent_profile_assignments.json` | Agent profile assignments (Pulse Pro) | 📝 Standard |
+| `profile-versions.json` | Agent profile version history (Pulse Pro) | 📝 Standard |
+| `profile-deployments.json` | Agent profile deployment status (Pulse Pro) | 📝 Standard |
+| `profile-changelog.json` | Agent profile change log (Pulse Pro) | 📝 Standard |
 | `recovery_tokens.json` | Recovery tokens (short-lived) | 🔒 **Sensitive** |
 | `sessions.json` | Persistent sessions (includes OIDC refresh tokens) | 🔒 **Sensitive** |
 | `update-history.jsonl` | Update history log (in-app updates) | 📝 Standard |
@@ -35,6 +39,7 @@ Pulse uses a split-configuration model to ensure security and flexibility.
 | `ai_patterns.json` | AI pattern detection data | 📝 Standard |
 | `ai_remediations.json` | AI remediation suggestions | 📝 Standard |
 | `ai_incidents.json` | AI incident tracking | 📝 Standard |
+| `org.json` | Organization metadata (multi-tenant) | 📝 Standard |

 Guest metadata entries are keyed by the canonical guest ID format `instance:node:vmid` (for example, `pve1:node1:100`). Legacy dash-separated keys are migrated automatically.

@@ -43,6 +48,11 @@ All files are located in `/etc/pulse/` (Systemd) or `/data/` (Docker/Kubernetes)
 Path overrides:
 - `PULSE_DATA_DIR` sets the base directory for `system.json`, encrypted files, and the bootstrap token.

+Multi-tenant layout:
+- Default org uses the root data directory for backward compatibility.
+- Non-default orgs store data under `/orgs/<org-id>/`.
+- Migration may create `/orgs/default/` and symlinks in the root data directory.
+
 ---

 ## 🔐 Authentication (`.env`)
@@ -142,6 +152,54 @@ Controls runtime behavior like logging, polling intervals, and UI preferences. L
 > **Note**: `autoUpdateTime` is stored by the UI, but the systemd timer uses its own schedule.
 </details>

+### Supported system.json Keys
+
+Numeric intervals are **seconds** unless noted otherwise.
+
+| Key | Description |
+| ----- | ----------- |
+| `pvePollingInterval` | PVE polling interval |
+| `pbsPollingInterval` | PBS polling interval |
+| `pmgPollingInterval` | PMG polling interval |
+| `backupPollingInterval` | Backup polling interval (`0` = auto) |
+| `backupPollingEnabled` | Enable backup polling |
+| `adaptivePollingEnabled` | Enable adaptive polling |
+| `adaptivePollingBaseInterval` | Base interval for adaptive polling |
+| `adaptivePollingMinInterval` | Minimum adaptive polling interval |
+| `adaptivePollingMaxInterval` | Maximum adaptive polling interval |
+| `connectionTimeout` | API connection timeout |
+| `logLevel` | Server log level (`debug`, `info`, `warn`, `error`) |
+| `allowedOrigins` | CORS allowlist (single origin or `*`) |
+| `allowEmbedding` | Allow iframe embedding |
+| `allowedEmbedOrigins` | Comma-separated `frame-ancestors` allowlist |
+| `webhookAllowedPrivateCIDRs` | Allowlist for private webhook targets |
+| `updateChannel` | Update channel (`stable` or `rc`) |
+| `autoUpdateEnabled` | Allow one-click updates |
+| `autoUpdateCheckInterval` | Update check interval (hours) |
+| `autoUpdateTime` | UI-stored preferred update time |
+| `publicURL` | Public URL used in links/notifications |
+| `hideLocalLogin` | Hide username/password login form |
+| `temperatureMonitoringEnabled` | Enable temperature monitoring (where supported) |
+| `dnsCacheTimeout` | DNS cache timeout |
+| `sshPort` | Default SSH port for temperature collection |
+| `discoveryEnabled` | Enable auto-discovery |
+| `discoverySubnet` | CIDR or `auto` |
+| `discoveryConfig` | Discovery tuning object (see below) |
+| `theme` | UI theme (`light`, `dark`, or empty for system) |
+| `fullWidthMode` | UI layout preference |
+| `metricsRetentionRawHours` | Raw metrics retention (hours) |
+| `metricsRetentionMinuteHours` | Minute metrics retention (hours) |
+| `metricsRetentionHourlyDays` | Hourly metrics retention (days) |
+| `metricsRetentionDailyDays` | Daily metrics retention (days) |
+| `disableDockerUpdateActions` | Hide Docker update actions in UI |
+| `backendPort` | Legacy (unused) |
+| `frontendPort` | Legacy (ignored; use `FRONTEND_PORT`) |
+
+`discoveryConfig` supports:
+- `environment_override`, `subnet_allowlist`, `subnet_blocklist`, `ip_blocklist`
+- `max_hosts_per_scan`, `max_concurrent`, `enable_reverse_dns`, `scan_gateways`
+- `dial_timeout_ms`, `http_timeout_ms`
+
 ### Common Overrides (Environment Variables)
 Environment variables take precedence over `system.json`.

--- a/docs/DEPLOYMENT_MODELS.md
+++ b/docs/DEPLOYMENT_MODELS.md
@@ -24,6 +24,7 @@ Pulse uses a split config model:

 - **Local auth and secrets**: `.env` (managed by Quick Security Setup or environment overrides, not shown in the UI)
 - **Encryption key**: `.encryption.key` (required to decrypt `.enc` files)
+- **Audit signing key**: `.audit-signing.key` (Pulse Pro, encrypted)
 - **System settings**: `system.json` (editable in the UI unless locked by env)
 - **Nodes and credentials**: `nodes.enc` (encrypted)
 - **Notification config**: `email.enc`, `webhooks.enc`, `apprise.enc` (encrypted)
@@ -43,16 +44,25 @@ Pulse uses a split config model:
 - **Guest metadata**: `guest_metadata.json`
 - **Agent profiles**: `agent_profiles.json`
 - **Agent profile assignments**: `agent_profile_assignments.json`
+- **Agent profile versions**: `profile-versions.json`
+- **Agent profile deployments**: `profile-deployments.json`
+- **Agent profile changelog**: `profile-changelog.json`
 - **Sessions**: `sessions.json` (persistent sessions, sensitive)
 - **Recovery tokens**: `recovery_tokens.json`
 - **Update history**: `update-history.jsonl`
 - **Metrics history**: `metrics.db` (SQLite)
+- **Organization metadata**: `org.json` (multi-tenant)

 Path mapping:

 - systemd/LXC: `/etc/pulse/*`
 - Docker/Helm: `/data/*`

+Multi-tenant layout:
+- Default org uses the root data dir for backward compatibility.
+- Non-default orgs use `/orgs/<org-id>/`.
+- Migration may create `/orgs/default/` and symlinks in the root data dir.
+
 ## Updates by Model

 ### systemd and Proxmox LXC
--- a/docs/METRICS_HISTORY.md
+++ b/docs/METRICS_HISTORY.md
@@ -58,18 +58,21 @@ These endpoints require authentication with the `monitoring:read` scope.

 `GET /api/metrics-store/history` supports:

- `resourceType` (required): `node`, `vm`, `container`, `storage`, `dockerHost`, `dockerContainer`
- `resourceId` (required): resource identifier (for VMs/containers use `instance:node:vmid`)
+- `resourceType` (required): `node`, `guest` (VM/LXC), `storage`, `docker`, `dockerHost`
+- `resourceId` (required): resource identifier (for guests use `instance:node:vmid`)
 - `metric` (optional): `cpu`, `memory`, `disk`, etc. Omit to return all metrics for the resource.
- `range` (optional): `1h`, `6h`, `12h`, `24h`, `7d`, `30d`, `90d` (default `24h`)
+- `range` (optional): `1h`, `6h`, `12h`, `24h`, `1d`, `7d`, `30d`, `90d` (default `24h`; duration strings also accepted)
+- `maxPoints` (optional): Downsample to a target number of points

 Example:

 ```bash
 curl -H "X-API-Token: $TOKEN" \
-  "http://localhost:7655/api/metrics-store/history?resourceType=vm&resourceId=pve1:node1:100&range=7d&metric=cpu"
+  "http://localhost:7655/api/metrics-store/history?resourceType=guest&resourceId=pve1:node1:100&range=7d&metric=cpu"
 ```

+> **License**: Requests beyond `7d` require the Pulse Pro `long_term_metrics` feature. Unlicensed requests return `402 Payment Required`.
+
 ## Troubleshooting

 - **No sparklines / empty history**: confirm the instance can write to the data directory and that `metrics.db` exists.
--- a/docs/MULTI_TENANT.md
+++ b/docs/MULTI_TENANT.md
@@ -66,6 +66,15 @@ All user-facing data endpoints use `getTenantMonitor(ctx)`:

 ---

+## Storage Layout and Migration
+
+- The **default** org uses the root data dir for backward compatibility.
+- Non-default orgs store data in `/orgs/<org-id>/`.
+- When multi-tenant is enabled, legacy single-tenant data is migrated into `/orgs/default/` and symlinks are created in the root data dir for compatibility.
+- Organization metadata is stored in `org.json` inside each org directory.
+
+---
+
 ## Intentionally Global (Admin-Level)

 These endpoints show system-wide data regardless of tenant context:
@@ -159,13 +168,10 @@ Legacy tokens (empty `OrgID`) have wildcard access during migration period.

 ### High Priority (Before GA)

- [ ] **Config deep copy**: `multi_tenant_monitor.go:59` does shallow copy; credential slices may be shared
- [ ] **Migration script**: Move existing data to `/orgs/default/` with symlinks for backward compatibility
 - [ ] **UI integration**: Org switcher, org management screens

 ### Medium Priority

- [ ] **Per-tenant node credentials**: Load tenant-specific `nodes.enc` instead of inheriting base config
 - [ ] **Org CRUD endpoints**: Create/update/delete organizations via API
 - [ ] **Member management**: Add/remove users from organizations

--- a/docs/UNIFIED_AGENT.md
+++ b/docs/UNIFIED_AGENT.md
@@ -84,6 +84,11 @@ curl -fsSL http://<pulse-ip>:7655/install.sh | \

 **Token resolution order**: `--token` → `--token-file` → `PULSE_TOKEN` → `/var/lib/pulse-agent/token`.

+### Advanced Flags
+
+- `--version`: Print the agent version and exit.
+- `--self-test`: Perform a self-test and exit (used during auto-update).
+
 ## Auto-Detection

 Auto-detection behavior: