laurence/apiscp-borg
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ACL/xattr-aware BorgBackup engine + native ApisCP panel/CLI integration
4 commits 1 branch 0 tags 124 KiB
Find a file
Laurence Horrocks-Barlow 02403b72c0 feat(borg): Layer 2 panel integration (module + two GUIs + hooks + installers) 
Native ApisCP integration, adapted from apiscp-kopia's Layer 2 against the real
borg Layer 1 subcommands:
- Borg_Module_Surrogate: admin + PRIVILEGE_SITE verbs, sudo boundary, config
  whitelist (now enforced), site-owner verbs derive the site from the auth
  context only, ownsDatabase gate, confirm-guarded destructive import.
- Admin GUI (apps/borg, "Borg Backups"): repository (BORG_REPO/passphrase/
  encryption/RSH, check-access, init, one-time recovery-key panel + download +
  irrecoverable tick), backup selection, retention + excludes + prune-now,
  schedule, maintenance (compact) + verify (check), notifications, tabbed layout,
  running overlay, double-submit guard, consolidated Restore workflow.
- Site-owner GUI (apps/myborgbackups, "My Borg Backups"): restore files / whole
  account / databases, run own backup, scoped to the caller's own site.
- Account hooks, install-layer2.sh, uninstall.sh (safe default, --purge).

Borg differences vs kopia are handled: no backend types/sftp/server, no browse/
subpath or point-in-time (restores newest archive; archive dates shown for info),
retention via config + `borg prune` (no global policy), import-db takes no
dumpfile. All PHP lints clean; controller verb calls all resolve to the module.
2026-07-24 23:18:35 +01:00
bin feat(borg): repository and restore tools (Layer 1 complete) 2026-07-24 22:49:24 +01:00
docs Initial scaffold: Borg engine + docs (Layer 1 milestone) 2026-07-24 22:33:37 +01:00
etc Initial scaffold: Borg engine + docs (Layer 1 milestone) 2026-07-24 22:33:37 +01:00
lib Initial scaffold: Borg engine + docs (Layer 1 milestone) 2026-07-24 22:33:37 +01:00
src feat(borg): Layer 2 panel integration (module + two GUIs + hooks + installers) 2026-07-24 23:18:35 +01:00
systemd Initial scaffold: Borg engine + docs (Layer 1 milestone) 2026-07-24 22:33:37 +01:00
.gitattributes chore: enforce LF line endings via .gitattributes 2026-07-24 22:33:56 +01:00
.gitignore Initial scaffold: Borg engine + docs (Layer 1 milestone) 2026-07-24 22:33:37 +01:00
install-layer2.sh feat(borg): Layer 2 panel integration (module + two GUIs + hooks + installers) 2026-07-24 23:18:35 +01:00
install.sh Initial scaffold: Borg engine + docs (Layer 1 milestone) 2026-07-24 22:33:37 +01:00
LICENSE Initial scaffold: Borg engine + docs (Layer 1 milestone) 2026-07-24 22:33:37 +01:00
README.md Initial scaffold: Borg engine + docs (Layer 1 milestone) 2026-07-24 22:33:37 +01:00
uninstall.sh feat(borg): Layer 2 panel integration (module + two GUIs + hooks + installers) 2026-07-24 23:18:35 +01:00

README.md

apiscp-borg

A BorgBackup backup engine for ApisCP, plus native panel/CLI integration, packaged so it survives ApisCP upgrades. Sibling project to apiscp-kopia: same architecture, different backend.

Why Borg, and why a plugin

Borg is a fast, deduplicating, compressing, encrypted backup tool. Unlike kopia, Borg preserves POSIX ACLs and extended attributes natively, which is exactly the metadata ApisCP encodes account permissions in. So a plugin is not needed to work around lost metadata (the reason apiscp-kopia exists). The value here is:

  • runs ApisCP's backup_dbs.php before archiving, so per-site database dumps are current instead of a day stale;
  • archives each site as its own named set (siteN-shadow-..., siteN-db-...), enabling single-site restore and per-site retention;
  • captures per-site databases through ApisCP's site-context export (a host-level dump cannot see them);
  • wires retention (borg prune), maintenance (borg compact), integrity (borg check), scheduling, email notifications, one-time key backup, and both an appliance-admin and a site-owner GUI into ApisCP.

See docs/DESIGN.md for how Borg changes the design relative to apiscp-kopia.

Architecture

Two decoupled layers, both upgrade-safe:

  • Layer 1: the engine. A standalone POSIX-sh program on a systemd timer, with no coupling to ApisCP's PHP internals. bin/borg-apiscp-backup plus borg-apiscp-repo and borg-apiscp-restore.
  • Layer 2: native integration. An ApisCP module, GUI apps, and account hooks under /usr/local/apnscp/config/custom, which survive upcp.

Requirements

  • ApisCP (any recent release)
  • borgbackup (borg) 1.2+ on the host (and on the remote for ssh backends)
  • a filesystem that carries ACLs and xattrs (default on ext4/xfs/btrfs)

Status

Early scaffold. The Layer 1 engine is the first milestone; the repository and restore tools, Layer 2 panel integration (module + two GUIs + hooks), install / uninstall, and full reference documentation are being built out to track the apiscp-kopia feature set. Not yet ready for production use.

License

MIT. See LICENSE.