mirror of
https://github.com/rcourtman/Pulse.git
synced 2026-09-11 14:00:29 +00:00
docs: remove fluff and simplify all documentation
- README reduced from 256 to 188 lines - FAQ reduced from 133 to 66 lines - PBS-AGENT simplified to essentials only - Removed marketing language, obvious advice, redundant sections - Focused on practical information users actually need
This commit is contained in:
Pulse Monitor
@@ -1,191 +1,61 @@
|
||||
# <img src="docs/images/pulse-logo.svg" alt="Pulse Logo" width="32" height="32" style="vertical-align: middle"> Pulse for Proxmox
|
||||
# Pulse for Proxmox
|
||||
|
||||
[](https://github.com/rcourtman/Pulse/releases/latest)
|
||||
[](https://hub.docker.com/r/rcourtman/pulse)
|
||||
[](LICENSE)
|
||||
Real-time monitoring for Proxmox VE and PBS with alerts and webhooks.
|
||||
|
||||
**Real-time monitoring for Proxmox VE and PBS with alerts, webhooks, and a clean web interface.**
|
||||
> **⚠️ Upgrading from v3?** See [Migration Guide](docs/MIGRATION_V3_TO_V4.md) - automatic upgrades will break.
|
||||
|
||||
> **⚠️ IMPORTANT: Upgrading from v3?** See the [Migration Guide](docs/MIGRATION_V3_TO_V4.md) - automatic upgrades will break your installation!
|
||||
|
||||
|
||||
|
||||
## Features
|
||||
|
||||
## Key Features
|
||||
- Live monitoring of VMs, containers, nodes, storage
|
||||
- Alerts with email and webhooks (Discord, Slack, Telegram, Teams, ntfy.sh, Gotify)
|
||||
- Unified view of PBS backups, PVE backups, and snapshots
|
||||
- PBS push mode for firewalled servers
|
||||
- Dark/light themes, responsive design
|
||||
- Built with Go for minimal resource usage
|
||||
|
||||
- **Real-time Monitoring** - Live updates for VMs, containers, nodes, and storage via WebSockets
|
||||
- **Smart Alerts** - Configurable thresholds with email and webhook notifications (Discord, Slack, Gotify, Telegram, ntfy.sh, Teams)
|
||||
- **Alert History** - Persistent storage of alert events with detailed metrics and timeline
|
||||
- **Unified Backups** - Single view for PBS backups, PVE backups, and snapshots
|
||||
- **PBS Push Mode** - Monitor isolated/firewalled PBS servers without inbound connections
|
||||
- **Modern UI** - Responsive design with dark/light themes, virtual scrolling, and expandable charts
|
||||
- **Performance** - Built with Go for minimal resource usage, stops polling when no clients connected
|
||||
- **Secure by Default** - Encrypted configuration storage with flexible credential management
|
||||
[Screenshots →](docs/SCREENSHOTS.md)
|
||||
|
||||
[View Screenshots →](docs/SCREENSHOTS.md)
|
||||
## Quick Start
|
||||
|
||||
## Support Development
|
||||
|
||||
Pulse is a solo hobby project developed in my free time. If you find it useful, your support helps keep me motivated and covers hosting costs.
|
||||
|
||||
[](https://github.com/sponsors/rcourtman)
|
||||
[](https://ko-fi.com/rcourtman)
|
||||
|
||||
## Quick Start (2 minutes)
|
||||
|
||||
### Prerequisites
|
||||
- Proxmox VE 7.0+ or PBS 2.0+
|
||||
- Network access to Proxmox API (ports 8006/8007)
|
||||
|
||||
### Install Pulse
|
||||
|
||||
Choose **one** method:
|
||||
### Install
|
||||
|
||||
```bash
|
||||
# Option A: Proxmox Helper Script - Creates dedicated LXC container (EASIEST)
|
||||
# Option A: Proxmox Helper Script (creates LXC container)
|
||||
bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/pulse.sh)"
|
||||
|
||||
# Option B: Docker (Multi-arch: AMD64, ARM64, ARMv7)
|
||||
docker run -d -p 7655:7655 -v pulse_data:/data --restart unless-stopped rcourtman/pulse:latest
|
||||
# Option B: Docker
|
||||
docker run -d -p 7655:7655 -v pulse_data:/data rcourtman/pulse:latest
|
||||
|
||||
# Option C: Manual Install (For existing LXC/VMs)
|
||||
# Option C: Manual (existing systems)
|
||||
curl -fsSL https://raw.githubusercontent.com/rcourtman/Pulse/main/install.sh | sudo bash
|
||||
```
|
||||
|
||||
### Configure Pulse
|
||||
### Configure
|
||||
|
||||
1. Open Pulse in your browser: `http://<your-server>:7655`
|
||||
2. Go to **Settings** → **Nodes** → **Add Node**
|
||||
3. Enter your Proxmox credentials
|
||||
4. Click **Save** - Pulse will start monitoring immediately
|
||||
1. Open `http://<your-server>:7655`
|
||||
2. Settings → Nodes → Add Node
|
||||
3. Enter Proxmox credentials
|
||||
4. Save
|
||||
|
||||
## Configuration
|
||||
|
||||
Pulse uses a modern, secure configuration system similar to popular apps like Radarr and Sonarr:
|
||||
|
||||
### Everything Through the UI
|
||||
|
||||
- **All configuration is done via the web interface** - no manual file editing needed
|
||||
- **Settings** → **Nodes**: Add/remove Proxmox instances with a simple form
|
||||
- **Settings** → **General**: Configure ports, intervals, themes, and more
|
||||
- **Alerts**: Set up thresholds and notification channels
|
||||
- **Configuration is encrypted** and stored securely with proper permissions
|
||||
|
||||
### Zero Configuration Files
|
||||
|
||||
Unlike traditional monitoring tools:
|
||||
- **No YAML/JSON files to edit**
|
||||
- **No environment variables to set**
|
||||
- **No complex configurations**
|
||||
- **Works immediately** after installation
|
||||
|
||||
Just open the web UI, add your Proxmox nodes through the interface, and you're done!
|
||||
|
||||
### Data Storage
|
||||
|
||||
- **Docker**: All data stored in `/data` (mount with `-v pulse_data:/data`)
|
||||
- **Manual Install**: All data stored in `/etc/pulse`
|
||||
- **Configuration**: Everything is managed through the web UI
|
||||
|
||||
### Configuration Backup & Migration
|
||||
|
||||
Pulse v4.0.3+ supports encrypted configuration export/import for backup and migration:
|
||||
## Docker
|
||||
|
||||
### Basic
|
||||
```bash
|
||||
# Export configuration (prompts for passphrase)
|
||||
pulse config export -o pulse-backup.enc
|
||||
|
||||
# Import on another instance
|
||||
pulse config import -i pulse-backup.enc
|
||||
|
||||
# Automated deployment (CI/CD)
|
||||
PULSE_PASSPHRASE=secret pulse config import -i backup.enc --force
|
||||
|
||||
# Docker with auto-import on first run
|
||||
docker run -d \
|
||||
-v pulse_data:/data \
|
||||
-v $(pwd)/pulse-backup.enc:/config.enc:ro \
|
||||
-e PULSE_INIT_CONFIG_FILE=/config.enc \
|
||||
-e PULSE_INIT_CONFIG_PASSPHRASE=secret \
|
||||
rcourtman/pulse:latest
|
||||
```
|
||||
|
||||
**Security Notes:**
|
||||
- Exports are encrypted with AES-256-GCM using your passphrase
|
||||
- Credentials remain encrypted throughout the export/import process
|
||||
- API endpoints (`/api/config/export`, `/api/config/import`) require API_TOKEN if configured
|
||||
- Perfect for Docker deployments and infrastructure as code workflows
|
||||
|
||||
### For Docker Users
|
||||
|
||||
Pulse provides multi-architecture Docker images supporting:
|
||||
- **linux/amd64** - Intel/AMD 64-bit servers
|
||||
- **linux/arm64** - 64-bit ARM (Raspberry Pi 4/5, Apple Silicon)
|
||||
- **linux/arm/v7** - 32-bit ARM (Raspberry Pi 2/3)
|
||||
|
||||
The only environment variables needed are for the initial ports if you want to change defaults:
|
||||
|
||||
```bash
|
||||
docker run -d -p 8080:8080 \
|
||||
-e PULSE_SERVER_FRONTEND_PORT=8080 \
|
||||
--name pulse \
|
||||
-p 7655:7655 \
|
||||
-v pulse_data:/data \
|
||||
--restart unless-stopped \
|
||||
rcourtman/pulse:latest
|
||||
```
|
||||
|
||||
Available Docker tags:
|
||||
- `rcourtman/pulse:latest` - Latest stable release
|
||||
- `rcourtman/pulse:4` - Latest v4.x release
|
||||
- `rcourtman/pulse:4.0.0` - Specific version
|
||||
|
||||
Once running, all configuration is done through the web UI.
|
||||
|
||||
### Security
|
||||
|
||||
Pulse automatically encrypts and secures all configuration:
|
||||
- Credentials are encrypted using AES-256-GCM
|
||||
- Configuration files have restricted permissions (0600)
|
||||
- No plaintext passwords in config files
|
||||
- Encryption keys derived from machine ID
|
||||
|
||||
See [Security Guide](docs/SECURITY.md) for additional security options.
|
||||
|
||||
## Webhooks
|
||||
|
||||
Pulse supports multiple webhook providers for alerts:
|
||||
|
||||
- **Discord** - Native Discord webhooks with rich embeds
|
||||
- **Slack** - Slack incoming webhooks
|
||||
- **Gotify** - Self-hosted push notifications
|
||||
- **Telegram** - Telegram bot notifications
|
||||
- **ntfy.sh** - Simple pub-sub notifications
|
||||
- **Teams** - Microsoft Teams incoming webhooks
|
||||
- **Generic** - Any webhook endpoint (JSON POST)
|
||||
|
||||
Configure webhooks in **Alerts** → **Destinations** → **Webhooks**.
|
||||
|
||||
## PBS Agent (Push Mode)
|
||||
|
||||
For isolated PBS servers that can't be reached directly:
|
||||
|
||||
```bash
|
||||
# On the PBS server:
|
||||
cd /opt
|
||||
wget https://github.com/rcourtman/Pulse/releases/latest/download/pulse-pbs-agent.tar.gz
|
||||
tar xzf pulse-pbs-agent.tar.gz
|
||||
cd pulse-pbs-agent
|
||||
./install.sh
|
||||
```
|
||||
|
||||
Configure the agent to push data to your Pulse instance. See [PBS Agent Guide](docs/PBS-AGENT.md).
|
||||
|
||||
## Docker Compose
|
||||
|
||||
### Docker Compose
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
pulse:
|
||||
image: rcourtman/pulse:latest # Multi-arch: AMD64, ARM64, ARMv7
|
||||
image: rcourtman/pulse:latest
|
||||
container_name: pulse
|
||||
ports:
|
||||
- "7655:7655"
|
||||
@@ -197,61 +67,122 @@ volumes:
|
||||
pulse_data:
|
||||
```
|
||||
|
||||
After starting, configure everything through the web UI at `http://localhost:7655`.
|
||||
### Unraid
|
||||
Available in Community Applications - search "Pulse for Proxmox"
|
||||
|
||||
## Building from Source
|
||||
## PBS Agent (Push Mode)
|
||||
|
||||
For isolated PBS servers that can't be reached directly:
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/rcourtman/Pulse.git
|
||||
cd Pulse
|
||||
# On PBS server
|
||||
curl -fsSL https://raw.githubusercontent.com/rcourtman/Pulse/main/install-pbs-agent.sh | sudo bash
|
||||
|
||||
# Build backend
|
||||
go build -o pulse ./cmd/pulse
|
||||
# Configure
|
||||
sudo nano /etc/pulse-pbs-agent/config.json
|
||||
# Add pulse_url and api_key
|
||||
|
||||
# Build frontend
|
||||
cd frontend-modern
|
||||
npm install
|
||||
npm run build
|
||||
sudo systemctl restart pulse-pbs-agent
|
||||
```
|
||||
|
||||
# Run
|
||||
./pulse
|
||||
[PBS Agent Details →](docs/PBS-AGENT.md)
|
||||
|
||||
## Configuration
|
||||
|
||||
All configuration through web UI:
|
||||
- **Settings → Nodes**: Add/remove Proxmox instances
|
||||
- **Settings → General**: Ports, intervals, themes
|
||||
- **Alerts**: Thresholds and notifications
|
||||
|
||||
Data locations:
|
||||
- **Docker**: `/data` volume
|
||||
- **Manual**: `/etc/pulse`
|
||||
|
||||
### Backup/Restore
|
||||
|
||||
```bash
|
||||
# Export (v4.0.3+)
|
||||
pulse config export -o backup.enc
|
||||
|
||||
# Import
|
||||
pulse config import -i backup.enc
|
||||
```
|
||||
|
||||
Or use Settings → Security tab in UI.
|
||||
|
||||
## Updates
|
||||
|
||||
### Docker
|
||||
```bash
|
||||
docker pull rcourtman/pulse:latest
|
||||
docker stop pulse
|
||||
docker rm pulse
|
||||
# Run docker run command again
|
||||
```
|
||||
|
||||
### Manual Install
|
||||
Settings → System → Check for Updates
|
||||
|
||||
## API
|
||||
|
||||
```bash
|
||||
# Status
|
||||
curl http://localhost:7655/api/status
|
||||
|
||||
# Metrics
|
||||
curl http://localhost:7655/api/metrics
|
||||
|
||||
# With authentication (if configured)
|
||||
curl -H "X-API-Token: your-token" http://localhost:7655/api/status
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
### Connection Issues
|
||||
- Check Proxmox API is accessible (port 8006/8007)
|
||||
- Verify credentials have PVEAuditor role minimum
|
||||
- For PBS: ensure API token has Datastore.Audit permission
|
||||
|
||||
1. **"Connection refused" error**
|
||||
- Check firewall rules for port 7655
|
||||
- Verify Pulse is running: `systemctl status pulse-backend`
|
||||
### High CPU/Memory
|
||||
- Reduce polling interval in Settings
|
||||
- Check number of monitored nodes
|
||||
- Disable unused features (backups, snapshots)
|
||||
|
||||
2. **"Invalid credentials" error**
|
||||
- Ensure user has at least `PVEAuditor` role
|
||||
- For PBS, user needs `DatastoreReader` permissions
|
||||
- Try token authentication instead of password
|
||||
### Logs
|
||||
```bash
|
||||
# Docker
|
||||
docker logs pulse
|
||||
|
||||
3. **No data showing**
|
||||
- Check browser console for errors
|
||||
- Verify Proxmox API is accessible from Pulse server
|
||||
- Check Pulse logs: `journalctl -u pulse -f`
|
||||
# Manual
|
||||
journalctl -u pulse -f
|
||||
```
|
||||
|
||||
### Getting Help
|
||||
## Security
|
||||
|
||||
- [Report Issues](https://github.com/rcourtman/Pulse/issues)
|
||||
- [Discussions](https://github.com/rcourtman/Pulse/discussions)
|
||||
- [FAQ](docs/FAQ.md)
|
||||
- Credentials stored encrypted (AES-256-GCM)
|
||||
- Optional API token authentication
|
||||
- Export/import requires passphrase
|
||||
- [Security Details →](docs/SECURITY.md)
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
# Frontend
|
||||
cd frontend-modern
|
||||
npm install
|
||||
npm run dev
|
||||
|
||||
# Backend
|
||||
go run cmd/pulse/*.go
|
||||
```
|
||||
|
||||
## Links
|
||||
|
||||
- [Releases](https://github.com/rcourtman/Pulse/releases)
|
||||
- [Docker Hub](https://hub.docker.com/r/rcourtman/pulse)
|
||||
- [Issues](https://github.com/rcourtman/Pulse/issues)
|
||||
- [Discord](https://discord.gg/hEEupTH2x3)
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
- Built with [Go](https://golang.org/) and [SolidJS](https://www.solidjs.com/)
|
||||
- Icons by [Lucide](https://lucide.dev/)
|
||||
- Inspired by the Proxmox community's monitoring needs
|
||||
|
||||
---
|
||||
|
||||
Made with ❤️ for the Proxmox community
|
||||
MIT - See [LICENSE](LICENSE)
|
||||
+38
-105
@@ -1,133 +1,66 @@
|
||||
# Frequently Asked Questions
|
||||
|
||||
## General
|
||||
|
||||
### What is Pulse?
|
||||
Pulse is a real-time monitoring tool for Proxmox Virtual Environment (PVE) and Proxmox Backup Server (PBS). It provides a modern web interface with alerts, webhooks, and comprehensive monitoring capabilities.
|
||||
|
||||
### Is Pulse free?
|
||||
Yes, Pulse is completely free and open source under the MIT license.
|
||||
|
||||
### What versions of Proxmox are supported?
|
||||
- Proxmox VE 7.0 and later
|
||||
- Proxmox Backup Server 2.0 and later
|
||||
# FAQ
|
||||
|
||||
## Installation
|
||||
|
||||
### What's the easiest way to install Pulse?
|
||||
The automated LXC container script is the easiest method:
|
||||
### What's the easiest way to install?
|
||||
```bash
|
||||
bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/pulse.sh)"
|
||||
```
|
||||
|
||||
### Can I run Pulse in Docker?
|
||||
Yes! Pulse has official Docker images:
|
||||
```bash
|
||||
docker run -d -p 7655:7655 -v pulse_config:/etc/pulse -v pulse_data:/data rcourtman/pulse:latest
|
||||
```
|
||||
|
||||
### What are the minimum system requirements?
|
||||
- CPU: 1 vCPU
|
||||
- RAM: 512MB (1GB recommended)
|
||||
- Disk: 1GB
|
||||
- Network: Access to Proxmox API
|
||||
### System requirements?
|
||||
- 1 vCPU, 512MB RAM (1GB recommended), 1GB disk
|
||||
- Network access to Proxmox API
|
||||
|
||||
## Configuration
|
||||
|
||||
### How do I add a Proxmox node?
|
||||
1. Open Pulse web UI
|
||||
2. Go to Settings → Nodes
|
||||
3. Click "Add Node"
|
||||
4. Enter your Proxmox credentials
|
||||
5. Click "Test Connection" then "Save"
|
||||
### How do I add a node?
|
||||
Settings → Nodes → Add Node → Enter credentials → Save
|
||||
|
||||
### What permissions does the Pulse user need?
|
||||
- For PVE: `PVEAuditor` role minimum
|
||||
- For PBS: `DatastoreReader` permission
|
||||
- For full features: `PVEAdmin` recommended
|
||||
### What permissions needed?
|
||||
- PVE: `PVEAuditor` minimum
|
||||
- PBS: `DatastoreReader` minimum
|
||||
|
||||
### Should I use username/password or API tokens?
|
||||
API tokens are more secure and recommended for production use. They can be created in Proxmox under Datacenter → Permissions → API Tokens.
|
||||
|
||||
### How do I configure alerts?
|
||||
1. Go to Alerts tab
|
||||
2. Set your thresholds for CPU, Memory, and Disk
|
||||
3. Add notification channels (email, webhooks)
|
||||
4. Configure alert schedule if needed
|
||||
### API tokens vs passwords?
|
||||
API tokens are more secure. Create in Proxmox: Datacenter → Permissions → API Tokens
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Why is Pulse not showing any data?
|
||||
1. Check if Pulse can reach your Proxmox server
|
||||
2. Verify credentials are correct
|
||||
3. Check firewall rules for ports 8006 (PVE) or 8007 (PBS)
|
||||
4. Look at Pulse logs: `journalctl -u pulse -f`
|
||||
### No data showing?
|
||||
- Check Proxmox API is reachable (port 8006/8007)
|
||||
- Verify credentials
|
||||
- Check logs: `journalctl -u pulse -f`
|
||||
|
||||
### Connection refused errors
|
||||
- Ensure port 7655 is not blocked
|
||||
- Check if Pulse is running: `systemctl status pulse`
|
||||
- Verify bind addresses in configuration
|
||||
### Connection refused?
|
||||
- Check port 7655 is open
|
||||
- Verify Pulse is running: `systemctl status pulse`
|
||||
|
||||
### Invalid credentials error
|
||||
- Ensure user exists in Proxmox
|
||||
- Check realm is correct (e.g., @pam, @pve)
|
||||
- For API tokens, ensure token is not expired
|
||||
- Verify user has required permissions
|
||||
### Invalid credentials?
|
||||
- Check username includes realm (@pam, @pve)
|
||||
- Verify API token not expired
|
||||
- Confirm user has required permissions
|
||||
|
||||
### High memory usage
|
||||
- This is usually from storing metrics history
|
||||
- Reduce `metricsRetentionDays` in settings
|
||||
- Restart Pulse to clear old metrics
|
||||
|
||||
## Security
|
||||
|
||||
### Is Pulse secure?
|
||||
Pulse is designed for internal networks. It uses encrypted storage for credentials and supports various security levels. See the [Security Guide](SECURITY.md) for details.
|
||||
|
||||
### Can I expose Pulse to the internet?
|
||||
This is not recommended. If needed:
|
||||
1. Use a reverse proxy with authentication
|
||||
2. Enable HTTPS
|
||||
3. Use strong passwords
|
||||
4. Consider VPN access instead
|
||||
|
||||
### How are credentials stored?
|
||||
Credentials are encrypted using AES-256-GCM and stored in `/etc/pulse/pulse.enc`. The encryption key is derived from the machine ID.
|
||||
### High memory usage?
|
||||
Reduce `metricsRetentionDays` in settings and restart
|
||||
|
||||
## Features
|
||||
|
||||
### Can Pulse monitor multiple Proxmox clusters?
|
||||
Yes! You can add multiple PVE and PBS instances in Settings → Nodes.
|
||||
### Multiple clusters?
|
||||
Yes, add multiple nodes in Settings
|
||||
|
||||
### Does Pulse support PBS in push mode?
|
||||
Yes, for isolated PBS servers, you can use the PBS agent that pushes data to Pulse.
|
||||
### PBS push mode?
|
||||
Yes, use PBS agent for isolated servers. See [PBS Agent docs](PBS-AGENT.md)
|
||||
|
||||
### What webhook providers are supported?
|
||||
- Discord
|
||||
- Slack
|
||||
- Gotify
|
||||
- Telegram
|
||||
- ntfy.sh
|
||||
- Microsoft Teams
|
||||
- Generic webhooks (any JSON endpoint)
|
||||
### Webhook providers?
|
||||
Discord, Slack, Gotify, Telegram, ntfy.sh, Teams, generic JSON
|
||||
|
||||
### Can I use Pulse with a reverse proxy?
|
||||
Yes, Pulse works well behind reverse proxies like Nginx, Caddy, or Traefik. Make sure to configure WebSocket support.
|
||||
|
||||
### Does Pulse have an API?
|
||||
Yes, Pulse provides a REST API. See the API section in the README for endpoints.
|
||||
### Works with reverse proxy?
|
||||
Yes, ensure WebSocket support is enabled
|
||||
|
||||
## Updates
|
||||
|
||||
### How do I update Pulse?
|
||||
- **Docker**: Pull the latest image and recreate the container
|
||||
- **LXC/Manual**: Use the update script or download the latest release
|
||||
- **From source**: Git pull and rebuild
|
||||
### How to update?
|
||||
- **Docker**: Pull latest image, recreate container
|
||||
- **Manual**: Settings → System → Check for Updates
|
||||
|
||||
### Will updates break my configuration?
|
||||
No, Pulse maintains backward compatibility. Your configuration is preserved during updates.
|
||||
|
||||
### How do I know when updates are available?
|
||||
- Watch the GitHub repository for releases
|
||||
- Check the version in Settings → About
|
||||
- Enable GitHub notifications for the project
|
||||
### Will updates break config?
|
||||
No, configuration is preserved
|
||||
+30
-209
@@ -1,240 +1,61 @@
|
||||
# PBS Agent Guide
|
||||
# PBS Agent (Push Mode)
|
||||
|
||||
The PBS Agent allows isolated or firewalled Proxmox Backup Servers to push their data to Pulse, eliminating the need for inbound connections.
|
||||
For PBS servers behind firewalls or in isolated networks that can't be reached by Pulse directly.
|
||||
|
||||
## When to Use PBS Agent
|
||||
|
||||
Use the PBS Agent when:
|
||||
- Your PBS server is behind a firewall with no inbound access
|
||||
- PBS is on an isolated network segment
|
||||
- You want to monitor PBS without opening firewall ports
|
||||
- Corporate security policies prevent inbound connections
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐
|
||||
│ PBS │ Push → │ Pulse │
|
||||
│ (Agent) │ --------> │ Server │
|
||||
│ Port: 8007 │ │ Port: 7655 │
|
||||
└─────────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
The agent runs on your PBS server and:
|
||||
1. Collects metrics locally via PBS API
|
||||
2. Pushes data to your Pulse server
|
||||
3. Handles connection failures gracefully
|
||||
4. Automatically retries on network issues
|
||||
|
||||
## Installation
|
||||
|
||||
### Quick Install
|
||||
## Quick Install
|
||||
|
||||
On your PBS server:
|
||||
|
||||
```bash
|
||||
# Download and extract
|
||||
cd /opt
|
||||
wget https://github.com/rcourtman/Pulse/releases/latest/download/pulse-pbs-agent.tar.gz
|
||||
tar xzf pulse-pbs-agent.tar.gz
|
||||
cd pulse-pbs-agent
|
||||
|
||||
# Run installer
|
||||
sudo ./install.sh
|
||||
```
|
||||
|
||||
### Manual Installation
|
||||
|
||||
1. **Download the agent binary**:
|
||||
```bash
|
||||
wget https://github.com/rcourtman/Pulse/releases/latest/download/pulse-pbs-agent
|
||||
chmod +x pulse-pbs-agent
|
||||
sudo mv pulse-pbs-agent /usr/local/bin/
|
||||
```
|
||||
|
||||
2. **Create configuration**:
|
||||
```bash
|
||||
sudo mkdir -p /etc/pulse-agent
|
||||
sudo nano /etc/pulse-agent/config.yml
|
||||
```
|
||||
|
||||
3. **Add configuration**:
|
||||
```yaml
|
||||
# Pulse server details
|
||||
pulse:
|
||||
url: http://your-pulse-server:7655
|
||||
token: your-agent-token # Generated in Pulse UI
|
||||
|
||||
# PBS connection
|
||||
pbs:
|
||||
host: https://localhost:8007
|
||||
user: monitor@pbs
|
||||
password: your-password
|
||||
# Or use API token:
|
||||
# tokenName: monitor
|
||||
# tokenValue: secret-token
|
||||
verifySSL: false
|
||||
|
||||
# Agent settings
|
||||
agent:
|
||||
interval: 30 # Seconds between updates
|
||||
name: pbs-prod # Unique name for this PBS
|
||||
```
|
||||
|
||||
4. **Create systemd service**:
|
||||
```bash
|
||||
sudo nano /etc/systemd/system/pulse-pbs-agent.service
|
||||
```
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Pulse PBS Agent
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/local/bin/pulse-pbs-agent
|
||||
Restart=always
|
||||
RestartSec=10
|
||||
User=pulse-agent
|
||||
Group=pulse-agent
|
||||
WorkingDirectory=/etc/pulse-agent
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
5. **Start the service**:
|
||||
```bash
|
||||
sudo useradd -r -s /bin/false pulse-agent
|
||||
sudo chown -R pulse-agent:pulse-agent /etc/pulse-agent
|
||||
sudo chmod 600 /etc/pulse-agent/config.yml
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now pulse-pbs-agent
|
||||
curl -fsSL https://raw.githubusercontent.com/rcourtman/Pulse/main/install-pbs-agent.sh | sudo bash
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Pulse Server Setup
|
||||
|
||||
1. In Pulse UI, go to **Settings** → **PBS Agents**
|
||||
2. Click **Add Agent**
|
||||
3. Enter a name and generate a token
|
||||
4. Copy the token for agent configuration
|
||||
|
||||
### Agent Configuration Options
|
||||
|
||||
```yaml
|
||||
pulse:
|
||||
url: http://pulse.example.com:7655 # Your Pulse server
|
||||
token: abc123... # Agent auth token
|
||||
timeout: 30 # Connection timeout (seconds)
|
||||
retryInterval: 60 # Retry interval on failure
|
||||
|
||||
pbs:
|
||||
host: https://localhost:8007 # PBS API endpoint
|
||||
user: monitor@pbs # PBS user
|
||||
password: secret # PBS password
|
||||
fingerprint: "AA:BB:CC..." # Optional TLS fingerprint
|
||||
verifySSL: true # Verify SSL certificates
|
||||
|
||||
agent:
|
||||
interval: 30 # Update interval (seconds)
|
||||
name: pbs-prod # Unique agent name
|
||||
logLevel: info # Log verbosity (debug|info|warn|error)
|
||||
Edit `/etc/pulse-pbs-agent/config.json`:
|
||||
```json
|
||||
{
|
||||
"pulse_url": "http://your-pulse-server:7655",
|
||||
"api_key": "your-api-key-from-pulse-settings",
|
||||
"poll_interval": 30,
|
||||
"pbs_url": "https://localhost:8007",
|
||||
"pbs_username": "apiuser@pbs",
|
||||
"pbs_token_name": "pulse",
|
||||
"pbs_token_value": "uuid-from-pbs"
|
||||
}
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
All settings can be overridden with environment variables:
|
||||
|
||||
```bash
|
||||
PULSE_URL=http://pulse:7655
|
||||
PULSE_TOKEN=your-token
|
||||
PBS_HOST=https://localhost:8007
|
||||
PBS_USER=monitor@pbs
|
||||
PBS_PASSWORD=secret
|
||||
AGENT_INTERVAL=60
|
||||
AGENT_NAME=pbs-backup
|
||||
```
|
||||
|
||||
## Monitoring Multiple PBS Servers
|
||||
|
||||
To monitor multiple PBS servers with agents:
|
||||
|
||||
1. Install the agent on each PBS server
|
||||
2. Use unique agent names for each
|
||||
3. Generate separate tokens in Pulse UI
|
||||
4. Each agent pushes to the same Pulse server
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Check Agent Status
|
||||
## Start Agent
|
||||
```bash
|
||||
sudo systemctl enable --now pulse-pbs-agent
|
||||
sudo systemctl status pulse-pbs-agent
|
||||
sudo journalctl -u pulse-pbs-agent -f
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
## Get API Key
|
||||
|
||||
**Agent can't connect to Pulse**:
|
||||
- Verify Pulse server URL is correct
|
||||
- Check network connectivity: `curl http://pulse-server:7655/api/health`
|
||||
- Ensure firewall allows outbound connections
|
||||
- Verify agent token is valid
|
||||
In Pulse web UI: Settings → General → API Key → Generate
|
||||
|
||||
**Agent can't connect to PBS**:
|
||||
- Check PBS API is accessible: `curl -k https://localhost:8007`
|
||||
- Verify PBS credentials
|
||||
- Ensure PBS user has DatastoreReader permission
|
||||
- Check SSL settings if using self-signed certificates
|
||||
## Create PBS Token
|
||||
|
||||
**High CPU usage**:
|
||||
- Increase the update interval
|
||||
- Check PBS API performance
|
||||
- Review agent logs for errors
|
||||
In PBS web UI:
|
||||
1. Configuration → Access Control → API Tokens
|
||||
2. Add Token
|
||||
3. User: Choose user with Datastore.Audit permission
|
||||
4. Copy token ID (username@pbs!tokenname) and secret
|
||||
|
||||
**Data not appearing in Pulse**:
|
||||
- Verify agent name matches configuration
|
||||
- Check Pulse logs for incoming data
|
||||
- Ensure agent token has correct permissions
|
||||
- Look for errors in agent logs
|
||||
## Verify
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Run the agent in debug mode:
|
||||
Check agent logs:
|
||||
```bash
|
||||
pulse-pbs-agent -debug
|
||||
journalctl -u pulse-pbs-agent -f
|
||||
```
|
||||
|
||||
Or set in config:
|
||||
```yaml
|
||||
agent:
|
||||
logLevel: debug
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Use API tokens** instead of passwords when possible
|
||||
2. **Secure the config file**: `chmod 600 /etc/pulse-agent/config.yml`
|
||||
3. **Use HTTPS** for Pulse server connections in production
|
||||
4. **Rotate tokens** periodically
|
||||
5. **Monitor agent logs** for suspicious activity
|
||||
In Pulse UI, PBS data should appear within 1 minute.
|
||||
|
||||
## Uninstall
|
||||
|
||||
```bash
|
||||
# Stop and disable service
|
||||
sudo systemctl stop pulse-pbs-agent
|
||||
sudo systemctl disable pulse-pbs-agent
|
||||
|
||||
# Remove files
|
||||
sudo rm -rf /etc/pulse-pbs-agent
|
||||
sudo rm /usr/local/bin/pulse-pbs-agent
|
||||
sudo rm -rf /etc/pulse-agent
|
||||
sudo rm /etc/systemd/system/pulse-pbs-agent.service
|
||||
sudo systemctl daemon-reload
|
||||
|
||||
# Remove user
|
||||
sudo userdel pulse-agent
|
||||
```
|
||||
Reference in New Issue
Block a user