backupsys agent

The backupsys agent is a Go service that runs scheduled backups to remote targets, keeps policy and state in SQLite, and exposes a local HTTP API (Gin) for management and health checks.

Privilege model: the process must run as root (Linux/macOS) or Administrator (Windows); the binary refuses to start otherwise.

---

1. What to deploy

Artifact	Notes
Binary	backupsys (Linux) / backupsys.exe (Windows), built from cmd/backup
Module	backup-system, Go 1.25+
State	SQLite database (paths below)
API	TCP listener on all interfaces (0.0.0.0) — plan firewall rules accordingly

---

2. System requirements

• OS: Linux (typical production), Windows Server/Desktop, or macOS (less common for servers).
• CPU/arch: build for your target (GOOS / GOARCH).
• Disk: space for SQLite, local staging/cache under configured base_path, and log rotation policy you define.
• Network: egress to backup targets (SFTP, rsync, rclone, etc., per backup_settings in DB).
• Privileges: elevated account for VSS/snapshot workflows on Windows and for writing system paths on Linux.

---

3. Build

From the pwbackup_agent directory:

CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o backupsys ./cmd/backup

Cross-compile (Linux + Windows amd64):

make -C scripts

Outputs: scripts/bin/backupsys, scripts/bin/backupsys.exe.

Pin the Go toolchain in CI (e.g. go.mod version) and record the git tag/commit in your release notes.

---

4. Filesystem layout

Linux

Purpose	Default / typical path
SQLite database	/var/lib/backupsys/backupsys.db
HTTP API port file	/etc/backupsys/port.conf (optional; see §5)
API key (HTTP server)	/etc/backupsys/auth.conf — format: key="your-token"
Config dir (legacy YAML path)	/etc/backupsys/ (--config retained for CLI compatibility)
Install base (if /opt writable)	/opt/backupsys (see utils.GetDefaultBasePath)

Create directories before first run as needed, with ownership matching the service user (usually root):

sudo install -d -m 0755 /var/lib/backupsys
sudo install -d -m 0755 /etc/backupsys

Windows

Purpose	Path
SQLite	C:\backupsys\db\backupsys.sqlite
CLI-generated API key	C:\backupsys\auth\auth.conf

Note: The HTTP server middleware loads the API key from /etc/backupsys/auth.conf in code (server/auth.go). On Linux, backupsys auth generate writes that same path when run as root. On Windows, confirm where your deployment stores the key so it matches what the server reads, or adjust your deployment convention accordingly.

---

5. HTTP API port

• Default port: 8654 if no config is found.
• Override with /etc/backupsys/port.conf:

PORT="8654"

Example template: port.conf.example.

---

6. Authentication

• Clients must send header: X-API-Key: <token>.
• Generate a key (after dirs exist):

sudo backupsys auth generate

• Production: restrict file mode (0600), rotate keys with a controlled process, and never commit auth.conf to version control.

---

7. Security (production checklist)

1. Firewall: The API binds to 0.0.0.0. Allow the agent port only from your control plane / VPN / bastion — not the public internet — unless you terminate TLS and auth elsewhere.
2. TLS: The embedded server is HTTP. If exposure crosses untrusted networks, put a reverse proxy with TLS in front, or restrict to loopback and use SSH tunnels.
3. Secrets: API key and SQLite may contain credentials metadata; backup and encrypt according to your policy.
4. Principle of least privilege: Even though the agent runs as root/admin for snapshots, limit who can reach the API and who can edit the DB or config files.

---

8. Install and run as a service

Built-in service (kardianos/service)

After placing the binary in your standard location (e.g. under base_path/bin on Windows as used by the installer flow):

sudo backupsys agent install
sudo backupsys agent start
sudo backupsys agent status

Logs and behavior follow app_config / DB-backed settings once the database is initialized.

Linux (systemd example)

If you prefer systemd instead of only the built-in helper, use a minimal unit (adjust paths):

[Unit]
Description=backupsys backup agent
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/backupsys agent --env production
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Run daemon-reload, enable, and start as usual.

---

9. Configuration model

• Primary source of truth: SQLite (app_config, backup_settings, backup_targets, etc.).
• --config: kept for CLI compatibility; effective settings are merged from the DB in normal operation (mustLoadConfig in cmd/backup/main.go).
• Validate connectivity after changes:

sudo backupsys config check

---

10. Health and monitoring

• Liveness-style check (requires API key):

curl -sS -H "X-API-Key: $(sudo backupsys auth show)" "http://127.0.0.1:8654/api/health"

Adjust host/port if you changed port.conf or use a tunnel.

• Agent version: backupsys --version
• DB inspection (break-glass): backupsys db list, backupsys db inspect -t backup_settings

Ship logs to your aggregator from the configured log directory (see app_config / defaults — logs are date-partitioned under that tree).

---

11. Operations

Task	Command / practice
On-demand backup	sudo backupsys run (--full for forced full)
List snapshots	backupsys list-snapshots
Graceful service stop	Use service manager / backupsys agent stop
Upgrade	Stop service → replace binary → run smoke test (config check, curl health) → start service
Backup state DB	Snapshot /var/lib/backupsys/backupsys.db when the service is stopped or use a filesystem snapshot for consistency

---

12. CLI quick reference

Command	Purpose
backupsys / backupsys agent	Default: agent + API; non-interactive = service runtime
backupsys agent then install, start, stop, status, or uninstall	Service lifecycle
backupsys run	Run backup now
backupsys config check	Database connectivity
backupsys db list / db inspect -t <table>	Inspect tables
backupsys auth generate / auth show	API token

Global flags: --config, --env (development|production), --debug, -v / --version.

---

13. Troubleshooting

Symptom	Things to verify
401 / missing api key	X-API-Key header; file exists where the server reads it
500 / auth configuration error	auth.conf missing, unreadable, or empty
API unreachable	Firewall, wrong port in port.conf, service not running
DB errors on start	Path permissions, disk full, SQLite not writable
Backup failures	Target credentials in DB, network, and method-specific tools (rsync, rclone, SFTP)

Enable short-term diagnosis with --debug only in controlled environments (more verbose logs).

---

14. Support matrix (summary)

• Production Linux: primary path — systemd or kardianos service, /var/lib/backupsys, /etc/backupsys for port and auth.
• Windows: full agent + service flows; validate API key path vs. server expectations for your environment.

For behavior details, follow cmd/backup/main.go (CLI), server/ (HTTP), internal/ (scheduler and backup run), and storage/ (schema and migrations).