diff --git a/docs/API.md b/docs/API.md index 9d77077fb..8239b7d20 100644 --- 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) diff --git a/docs/CENTRALIZED_MANAGEMENT.md b/docs/CENTRALIZED_MANAGEMENT.md index 7da6c2953..eb89e4d21 100644 --- 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 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 +``` + +```http +POST /api/admin/profiles/validate +Authorization: Bearer +Content-Type: application/json + +{ + "config": { + "interval": "60s", + "enable_docker": true + } +} +``` + +Optional AI suggestions: + +```http +POST /api/admin/profiles/suggestions +Authorization: Bearer +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 +``` + +Rollback to a specific version: + +```http +POST /api/admin/profiles/{id}/rollback/{version} +Authorization: Bearer +``` + +### 9. Change Log and Deployment Status + +Change log entries are stored in `profile-changelog.json`: + +```http +GET /api/admin/profiles/changelog +Authorization: Bearer +``` + +Deployment status is stored in `profile-deployments.json`: + +```http +GET /api/admin/profiles/deployments +Authorization: Bearer +``` + +Update deployment status via: + +```http +POST /api/admin/profiles/deployments +Authorization: Bearer +Content-Type: application/json +``` + ## Agent Behavior 1. On startup, the agent computes its Agent ID. diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 9cb9dbde0..51b1dc88e 100644 --- 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//`. +- 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. +### 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`. diff --git a/docs/DEPLOYMENT_MODELS.md b/docs/DEPLOYMENT_MODELS.md index a85795ddb..435be3f02 100644 --- 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//`. +- Migration may create `/orgs/default/` and symlinks in the root data dir. + ## Updates by Model ### systemd and Proxmox LXC diff --git a/docs/METRICS_HISTORY.md b/docs/METRICS_HISTORY.md index 78b29d0f9..0b33d46e6 100644 --- 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. diff --git a/docs/MULTI_TENANT.md b/docs/MULTI_TENANT.md index f6ac8faaf..3891ccc8d 100644 --- 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//`. +- 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 diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.md index 6260a292f..c08ea47a6 100644 --- a/docs/UNIFIED_AGENT.md +++ b/docs/UNIFIED_AGENT.md @@ -84,6 +84,11 @@ curl -fsSL http://: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: