80 lines
3.0 KiB
Markdown
80 lines
3.0 KiB
Markdown
# VPS Control
|
|
|
|
Production-oriented monitoring and constrained management for Debian and Ubuntu
|
|
VPS hosts. A small Rust daemon exposes semantic system APIs over a private
|
|
WireGuard or TLS network. A separately hosted Go + React control plane provides
|
|
inventory, history, RBAC, and an immutable audit trail.
|
|
|
|
```text
|
|
Browser ──HTTPS──> React/nginx ──> Go API ──private network──> Rust agent
|
|
│
|
|
PostgreSQL
|
|
▲
|
|
Grafana (Prometheus/Loki APIs)
|
|
```
|
|
|
|
The project intentionally has no remote shell. The agent defaults to
|
|
`127.0.0.1:9105`, reads credentials from root-managed files, runs as an
|
|
unprivileged system user, and is bounded by systemd resource controls.
|
|
|
|
## Quick start
|
|
|
|
Control plane:
|
|
|
|
```bash
|
|
cp control-plane/.env.example control-plane/.env
|
|
# Fill all CHANGE_ME values and create the secret files documented below.
|
|
docker compose -f control-plane/docker-compose.yml up -d --build
|
|
```
|
|
|
|
Agent development build:
|
|
|
|
```bash
|
|
cargo build --manifest-path agent/Cargo.toml --release
|
|
sudo install -m 0755 agent/target/release/vps-agent /usr/local/bin/vps-agent
|
|
sudo install -m 0640 examples/agent-config.toml /etc/vps-agent/config.toml
|
|
```
|
|
|
|
For a release installation, download the lifecycle script and checksum as
|
|
separate files, verify with `sha256sum -c`, then run:
|
|
|
|
```bash
|
|
sudo ./scripts/vps-agentctl.sh install --version v0.1.0
|
|
```
|
|
|
|
See [deployment](docs/deployment.md), [security](docs/security.md), and the
|
|
[agent](agent/README.md) and [control-plane](control-plane/README.md) manuals.
|
|
|
|
## Repository
|
|
|
|
```text
|
|
agent/ Rust VPS daemon and systemd packaging
|
|
control-plane/backend/ Go API, PostgreSQL persistence, auth/RBAC/audit
|
|
control-plane/frontend React/Vite dashboard
|
|
docs/ architecture, threat model, operations, development
|
|
scripts/ safe agent lifecycle utility
|
|
examples/ deployable configuration examples
|
|
```
|
|
|
|
## Security and compatibility
|
|
|
|
Supported targets are Debian 12+, Ubuntu 22.04, and Ubuntu 24.04 with systemd.
|
|
Keep the agent behind WireGuard or localhost/reverse tunnel. Never bind it to a
|
|
public address without TLS, host firewall policy, and an explicit risk review.
|
|
Read [docs/security.md](docs/security.md) before enabling write operations.
|
|
|
|
The current v1 scope supports read-only system, network, socket, firewall,
|
|
Fail2Ban, WireGuard, and allow-listed service inspection; manual Fail2Ban
|
|
ban/unban and service restart are audited. Managed firewall transactions and L7
|
|
rate-limit configuration are deliberately deferred until a separately
|
|
privileged helper can guarantee crash-safe rollback.
|
|
|
|
Optional observability endpoints make the backend a constrained
|
|
Prometheus-compatible metrics source and Loki-compatible log source for
|
|
Grafana. Grafana never receives an agent address or agent credential.
|
|
|
|
## Development
|
|
|
|
See [docs/development.md](docs/development.md). CI-compatible commands are also
|
|
listed in [AGENTS.md](AGENTS.md). This repository is licensed under Apache-2.0.
|