endssh/pxmon
SHA256
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

chore: publish pxmon v0.2.0

Browse Source
This commit is contained in:
endssh
2026-06-16 21:52:10 +04:00
commit 6b703db02b
69 changed files with 25886 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ARCHITECTURE.md
+29
View File
@@ -0,0 +1,29 @@
# Architecture
## Components
- `cmd/pxmon`: main CLI and TUI entrypoint.
- `cmd/pxmon-agent`: node-side agent binary.
- `internal/cli`: command parsing, TUI, bot integration, UX flows.
- `internal/cluster`: cluster model/store/service, SSH operations, alerts, reports, backup/runbooks/scheduler.
- `internal/history`: metrics history stores and chart helpers.
- `internal/agent`: agent API server and stats collection types.
## Data model
- Registry is encrypted and stored locally.
- Default path: `<user-config-dir>/pxmon/clusters.enc`
- Master key path defaults to `<user-config-dir>/pxmon/master.key`
- Supports environment overrides:
- `PXMON_CONFIG`
- `PXMON_MASTER_KEY`
## Runtime flow
1. User invokes CLI/TUI command.
2. `internal/cli` resolves cluster selector and command flags.
3. `internal/cluster.Service` performs SSH/agent calls.
4. Results are rendered in CLI tables/JSON or TUI panels.
5. Optional telemetry/history snapshots are persisted for trends.
## Security model
- Local registry encryption with a generated master key.
- Locker subsystem can block operational commands until unlock.
- Config export/import supports passphrase-protected bundles.
docs/COMMANDS.md
+119
View File
@@ -0,0 +1,119 @@
# Command Reference
## Root
- `pxmon [--config path] [--json] <command>`
- `pxmon help`
- `pxmon shell` (interactive alias to TUI)
- `pxmon tui [name-or-id] [--interval 2s] [--iface eth0]`
- `pxmon clusters [name-or-id] [--interval 2s] [--iface eth0]`
- `pxmon network [name-or-id] [--interval 2s] [--iface eth0]`
- `pxmon cluster ...`
- `pxmon bot ...`
- `pxmon locker ...`
- `pxmon config ...`
- `pxmon export ...` (shortcut)
- `pxmon import ...` (shortcut)
- `pxmon explain [--find text]`
## Cluster command tree
- `connect|add`
- `list|ls`
- `show|get`
- `current`
- `use`
- `disconnect|remove|rm`
- `set-auth|auth|password|passwd`
- `openssh|ssh`
- `exec|run <name-or-id> -- <command>`
- `ping|check`
- `bootstrap`
- `agent`
- `status [name-or-id]`
- `adopt-auth|sync-auth|repair-auth [name-or-id]`
- `update [name-or-id] [--restart-bot=true|false]`
- `versions|version-list`
- `stats [name-or-id] [--once]`
- `usage [name-or-id] --range live|1h|1d|1mo|all [--du /]`
- `traffic [name-or-id] --range 1h|1d|1mo|all`
- `graph [name-or-id] --range 1h|1d|1mo|all [--out file.png]`
- `p95 [name-or-id] --iface <iface> --range <duration> [--graph]`
- `slo|availability [name-or-id] --range 7d|30d|all`
- `capacity forecast [name-or-id] --range 7d|30d|all`
- `alert|alerts show|set [name-or-id]`
- `alert-routing|routing show|set [name-or-id]`
- `alert-vm|vm-alert show|set|check [name-or-id]`
- `software|plugins show|scan [name-or-id]`
- `tag|tags add|rm|ls [name-or-id] --tags a,b`
- `kvm-tag|vm-tag add|rm|ls [name-or-id] --vm <name> --tags a,b`
- `change-history|changes [--tail N]`
- `drift [name-or-id]`
- `baseline set|show [name-or-id]`
- `ack [name-or-id] --kind <kind> --for 24h`
- `report export --format json|csv --out <path>`
- `backup`
- `target add|ls|rm|test`
- `plan add|ls|rm|run`
- `run <plan-id-or-name>`
- `repo-tunnel|repo|repo-tunneling`
- `gateway-script --allow <ip-or-cidr> [--port 3128]`
- `gateway-setup <gateway-node> --allow <ip-or-cidr> [--port 3128]`
- `enable <name-or-id> --gateway <host:port> --table <id> [--gateway-ip <ip>] [--manager auto|apt|dnf|yum]`
- `install <name-or-id> --gateway <host:port> --table <id> -- <command>`
- `status <name-or-id>`
- `disable <name-or-id> --gateway <host:port> --table <id>`
- `runbook`
- `list`
- `show <id>`
- `run <id>`
- `add --id ... --name ... --step ...`
- `add --edit`
- `add --from <path>`
- `rm <id>`
- `runbook-trigger show|set [name-or-id]`
- `schedule|scheduler`
- `add --name ... --cmd ... --every ...`
- `add --edit`
- `add --from <path>`
- `ls`
- `rm <task-id-or-name>`
- `run-due`
- `start [--interval 30s]`
- `stop`
- `status`
- `logs [--tail 200]`
- `worker [--interval 30s]`
## Bot
- `pxmon bot telegram show [--show-token]`
- `pxmon bot telegram set --token <token> --allow <id> [--allow <id> ...]`
- `pxmon bot telegram disable`
- `pxmon bot telegram restart [--poll 2s]`
- `pxmon bot telegram logs [--tail 200]`
- `pxmon bot telegram run [--poll 2s]`
## Locker
- `pxmon locker status`
- `pxmon locker set [--password <pw>]`
- `pxmon locker unlock [--password <pw>]`
- `pxmon locker lock`
- `pxmon locker disable`
- `pxmon locker logs [--tail 200]`
## Config
- `pxmon config export [<path>] [--out <path>] [--password <pw>]`
- `pxmon config import <path> [--password <pw>] [--replace]`
## In-TUI command console
Alias examples:
- `alerts ...` -> `cluster alert ...`
- `connect <name>` -> `cluster use <name>`
- `software ...` -> `cluster software ...`
- `clusters` -> `cluster list`
- `ping <name>` -> `cluster ping <name>`
Plugin-style commands from console:
- `kvm list|start|stop|reboot|top|net-top`
- `lxc list|start|stop|restart|stats|top|net-top`
- `lxd list|start|stop|restart|stats|top|net-top`
- `bird status|protocols|routes`
- `frr status|routes|bgp|ospf`
docs/FEATURES.md
+67
View File
@@ -0,0 +1,67 @@
# Feature Overview
## 1) Cluster inventory and connectivity
- Register clusters by SSH host/user/auth method.
- Keep one active cluster for short commands.
- Validate connectivity at connect time (or allow deferred validation).
- Support direct agent transport or SSH-tunneled transport (`ipfabric`).
- Store SSH key passphrases directly or via a passphrase file reference.
## 2) Interactive TUI operations
- Multi-view dashboard for overview, cluster inventory, network, settings, docs, usage, and live data.
- Integrated command console with history and aliases.
- Scrollable fixed-size panes for stable rendering.
- Privacy mode for masking sensitive output.
## 3) Agent lifecycle
- Build and bootstrap `pxmon-agent` remotely via SSH.
- Query agent status across all clusters.
- Compare node agent version with expected local version.
- Update and optionally restart bot processes.
## 4) Monitoring and analytics
- Realtime stats snapshots.
- Historical usage windows (`live`, `1h`, `1d`, `1mo`, `all`).
- Traffic p95 and usage chart generation (PNG output).
- SLO reports and capacity forecasting.
## 5) Alerting and policy controls
- CPU/RAM/SWAP/DISK/NET threshold policies.
- Sustained network threshold detection.
- VM alert policy (e.g., minimum running VMs, shutoff warnings).
- Alert routing behavior controls (critical immediate vs warning batches).
## 6) Drift and change management
- Drift checks for configuration/runtime mismatches.
- Baseline set/show and timed acknowledgment.
- Change history inspection.
## 7) Tagging and grouping
- Cluster tags (add/remove/list).
- KVM VM-level tags.
## 8) Backup and disaster readiness
- Backup targets (SFTP/S3).
- Backup plans with schedules and retention settings.
- Manual backup run execution.
- Export/import bundles can carry referenced SSH/SFTP key files.
## 9) RepoTunneling
- Prepare a restricted squid gateway for repository traffic.
- Temporarily configure apt/dnf/yum proxy settings on `ipfabric` nodes.
- Run one-shot package install commands and clean up the route/proxy state.
## 10) Runbooks and automation
- Define and execute runbooks.
- Configure runbook triggers for selected alert conditions.
- Scheduler for periodic command execution.
## 11) Telegram bot integration
- Configure token and allow-list.
- Run/restart/disable bot daemon.
- Tail bot logs.
## 12) Security and data management
- Encrypted local registry storage.
- Locker controls to block critical commands until unlock.
- Encrypted export/import bundles for migration and backup.
docs/INSTALL.md
+41
View File
@@ -0,0 +1,41 @@
# Install and Build
## Prerequisites
- Go 1.25+
- Git
- SSH client access to managed hosts
## Clone and build
```bash
git clone https://git.datacoria.com/endssh/pxmon.git
cd pxmon
go mod tidy
go test ./...
go build -o bin/pxmon ./cmd/pxmon
go build -o bin/pxmon-agent ./cmd/pxmon-agent
```
## Run
```bash
./bin/pxmon
```
## Build with explicit agent version metadata
`pxmon-agent` exposes build-time version in API responses.
```bash
go build -ldflags "-X pxmon/internal/agent.Version=v0.2.0" -o bin/pxmon-agent ./cmd/pxmon-agent
```
## Optional install to PATH
```bash
install -m 0755 bin/pxmon /usr/local/bin/pxmon
install -m 0755 bin/pxmon-agent /usr/local/bin/pxmon-agent
```
## Verify
```bash
pxmon cluster help
pxmon bot telegram --help
pxmon config --help
```
docs/PUBLISH.md
+28
View File
@@ -0,0 +1,28 @@
# Publish to Gitea
## 1) Initialize repository
```bash
git init --object-format=sha256
git checkout -b main
git add .
git commit -m "chore: publish pxmon v0.2.0"
```
## 2) Create remote and push
```bash
git branch -M main
git remote add origin https://git.datacoria.com/endssh/pxmon.git
git push -u origin main
```
## 3) Create release tag
```bash
git tag v0.2.0
git push origin v0.2.0
```
## 4) Optional repository settings
- Enable branch protection for `main`
- Enable Dependabot alerts
- Add issue labels and project board
- Add release notes for tag `v0.2.0`
docs/RELEASES.md
+30
View File
@@ -0,0 +1,30 @@
# Releases and Versioning
## Versioning policy
This project follows Semantic Versioning:
- `MAJOR`: breaking CLI/API/data changes
- `MINOR`: backward-compatible features
- `PATCH`: backward-compatible fixes
Current project version is tracked in [`VERSION`](../VERSION).
## Release process
1. Update `VERSION`.
2. Add new section in `CHANGELOG.md` with date and changes.
3. Run:
- `go test ./...`
- `go build -o bin/pxmon ./cmd/pxmon`
- `go build -o bin/pxmon-agent ./cmd/pxmon-agent`
4. Tag release:
- `git tag vX.Y.Z`
- `git push origin vX.Y.Z`
## Versions list
- `v0.2.0` (2026-06-16): RepoTunneling, remote exec, key passphrase files, export/import key-file restore, and release cleanup.
- `v0.1.0` (2026-04-17): initial open-source packaging release.
## Agent versions
Known agent versions are stored in:
- `internal/cluster/agent_versions.json`
This list is used by agent status/drift checks to flag outdated nodes.
docs/REPOTUNNELING.md
+103
View File
@@ -0,0 +1,103 @@
# PXmon RepoTunneling
RepoTunneling gives an `ipfabric` node temporary package repository access
through a disposable gateway VM.
The node does not receive full internet access. PXmon only adds an `ip rule`
for the gateway VM address and configures the node package manager to use the
gateway as an HTTP proxy.
## Topology
```text
ipfabric node
-> ip rule to gateway public IP using the node-specific routing table
-> gateway VM with squid
-> internet repositories
```
The routing table is not hard-coded. Always pass the correct table for that
node with `--table`.
## 1. Prepare The Gateway VM
The gateway VM must have normal internet access and must be reachable from the
ipfabric node after adding the destination-specific route rule.
If the gateway VM is already managed by PXmon:
```bash
pxmon cluster repo-tunnel gateway-setup repo-vm \
--allow 198.51.100.20/32 \
--port 3128
```
If it is not managed by PXmon, print the setup script and run it manually on the
gateway VM:
```bash
pxmon cluster repo-tunnel gateway-script \
--allow 198.51.100.20/32 \
--port 3128
```
Use one `--allow` per node source IP/CIDR. Do not leave squid open to the
internet.
## 2. Enable RepoTunneling On The ipfabric Node
```bash
pxmon cluster repo-tunnel enable edge-node-1 \
--gateway 203.0.113.10:3128 \
--gateway-ip 203.0.113.10 \
--table 1010 \
--manager dnf
```
`--gateway-ip` is optional when the node can resolve the gateway hostname or
when `--gateway` is already an IP. It is useful before DNS works through the
proxy path.
PXmon writes managed package-manager config:
- apt: `/etc/apt/apt.conf.d/99-pxmon-repo-tunnel`
- dnf: managed block in `/etc/dnf/dnf.conf`
- yum: managed block in `/etc/yum.conf`
## 3. Install Packages
For a one-shot package operation:
```bash
pxmon cluster repo-tunnel install edge-node-1 \
--gateway 203.0.113.10:3128 \
--gateway-ip 203.0.113.10 \
--table 1010 \
--manager dnf \
-- dnf install -y curl jq smartmontools
```
By default `install` removes the proxy config and matching `ip rule` after the
command. Add `--keep-enabled` if you want to leave it active.
## 4. Inspect Or Disable
```bash
pxmon cluster repo-tunnel status edge-node-1
```
```bash
pxmon cluster repo-tunnel disable edge-node-1 \
--gateway 203.0.113.10:3128 \
--gateway-ip 203.0.113.10 \
--table 1010
```
## Notes
- `--table` is required because ipfabric route table IDs differ between
servers.
- Use `--no-rule` only if you already created the needed route rule manually
and only want PXmon to manage package proxy config.
- For AlmaLinux 8, `--manager dnf` is the expected mode.
- The gateway should be disposable and firewall-restricted.
docs/TUI.md
+40
View File
@@ -0,0 +1,40 @@
# TUI Guide
## Views
- `overview`
- `clusters`
- `network`
- `settings`
- `docs`
- `usage`
- `live`
## Main hotkeys
- `tab` switch views
- `o/c/n/s/d/u` jump to overview/clusters/network/settings/docs/usage
- `t` open command console
- `ctrl+t` fullscreen command console
- `ctrl+g` leave command console
- `r` refresh
- `q` quit
## Scrolling
- Main content scroll: `alt+up` / `alt+down`
- Docs view scroll: arrows, `j/k`, `PgUp/PgDn`, `Home/End`
- Network view: navigation with arrows + page controls
## Console mode
Built-ins:
- `help`
- `history`
- `clear`
- `overview`, `clusters`, `network`, `settings`, `docs`
- `quit`
Advanced:
- End line with `\` for multiline command continuation
- Shell escape with `!<command>`
## Privacy mode
- Toggle with `alt+p`
- Redacts sensitive patterns in rendered output
docs/USAGE.md
+92
View File
@@ -0,0 +1,92 @@
# Usage Guide
## Start TUI
```bash
pxmon
# or
pxmon tui
```
## Add a cluster
```bash
pxmon cluster connect \
--name eu-1 \
--host 10.0.0.10 \
--user root \
--auth key \
--key-path ~/.ssh/id_ed25519
```
## Set active cluster
```bash
pxmon cluster use eu-1
```
## Connectivity checks
```bash
pxmon cluster ping eu-1
pxmon cluster ping eu-1 --agent
```
## Agent lifecycle
```bash
pxmon cluster bootstrap eu-1
pxmon cluster agent status eu-1
pxmon cluster agent update eu-1 --restart-bot=true
pxmon cluster agent versions
```
## Monitoring and history
```bash
pxmon cluster stats eu-1 --once
pxmon cluster usage eu-1 --range 1d
pxmon cluster traffic eu-1 --range 30d
pxmon cluster graph eu-1 --range 1d --out ./eu-1-1d.png
pxmon cluster p95 eu-1 --iface eth0 --range 30d --graph
```
## Alerts
```bash
pxmon cluster alert set eu-1 --cpu 85 --ram 90 --disk 90 --net-mbps 300
pxmon cluster alert-routing set eu-1 --critical-immediate=true --warning-batch-mins 5
pxmon cluster alert-vm set eu-1 --enabled --warn-on-shutoff --min-running 100
```
## Drift, SLO, capacity
```bash
pxmon cluster drift eu-1
pxmon cluster drift baseline set eu-1
pxmon cluster slo eu-1 --range 30d
pxmon cluster capacity forecast eu-1 --range 30d
```
## Backup, runbooks, scheduler
```bash
pxmon cluster backup target add --name b2 --type s3 --s3-endpoint s3.example.net --s3-bucket backups --s3-access-key AKIA... --s3-secret-key ...
pxmon cluster backup plan add --name vm-images --cluster eu-1 --target b2 --path /var/lib/libvirt/images --every 6h
pxmon cluster backup run vm-images
pxmon cluster runbook list
pxmon cluster runbook run vm-health-check
pxmon cluster schedule add --name audit --cmd 'cluster drift eu-1' --every 30m
pxmon cluster schedule start --interval 30s
```
## Telegram bot
```bash
pxmon bot telegram set --token <token> --allow <id> --allow <id>
pxmon bot telegram show
pxmon bot telegram restart
pxmon bot telegram logs --tail 100
```
## Locker and config bundles
```bash
pxmon locker set --password 'strong-pass'
pxmon locker status
pxmon locker unlock --password 'strong-pass'
pxmon config export --out ./pxmon-export.enc
pxmon config import ./pxmon-export.enc --replace
```