Grayhaven Systems LLC Backup (grayhaven-backupctl)

Operator-friendly backup and restore utility for Grayhaven Systems LLC managed servers.

Table of Contents

• Scope
• Managed Environment
• Quick Usage
• Documentation
• Contributing
• License

Scope

grayhaven-backupctl wraps the restic repositories configured by grayhaven-config-ansible for Grayhaven Systems LLC managed servers. It gives operators one command for common backup review, search, and restore tasks while leaving restic as the authoritative backup engine.

The utility supports:

• local and optional remote restic repositories;
• local-first restore selection when both repositories contain the requested path;
• natural-language and explicit timestamp filters;
• file, directory, glob, and path-file restore selection;
• in-place restore that merges directories and confirms each conflicting entry;
• target-directory restore that preserves the archived absolute path tree and merges it with existing content;
• SELinux context restoration after files are restored;
• journald logging for backup and restore actions.

Show the immutable semantic version and the checked-out commit identity:

grayhaven-backupctl --version
# grayhaven-backupctl 1.0.0-<short-commit-sha>

In a Git checkout, the suffix is resolved from the actual HEAD commit. An installed copy without adjacent Git metadata uses a COMMIT_SHA file beside the copied implementation. That file must contain exactly one lowercase 40-hex commit ID followed by one newline. Checkout Git metadata takes precedence; if neither source is valid, --version fails clearly.

For the canonical contributor version and release-tag procedure, see Version Workflow.

Back to top

Managed Environment

grayhaven-backupctl is installed and maintained by grayhaven-config-ansible on Grayhaven Systems LLC managed servers. It expects the host layout, restic configuration, backup runner, system packages, and optional remote backup credentials managed by that repository.

This repository is not a general-purpose backup utility template. Using similar automation outside the Grayhaven Systems LLC managed environment requires review and adaptation.

Back to top

Quick Usage

List local and remote backups:

sudo grayhaven-backupctl list

List recent backups:

sudo grayhaven-backupctl list --since "2 days ago"

Create local and remote backups, when remote backups are configured:

sudo grayhaven-backupctl backup

Find local or remote backups that contain a path:

sudo grayhaven-backupctl find --path /home/example/report.txt

List the contents of a directory from the latest backup recursively:

sudo grayhaven-backupctl ls latest --path /home/example --recursive

Restore a file to a target directory:

sudo grayhaven-backupctl restore --target /tmp/grayhaven-restore --path /tmp/report.txt

Restore a file to its original location:

sudo grayhaven-backupctl restore --in-place --path /home/example/report.txt

Back to top

Documentation

Operator backup and restore procedures are documented in Operations.

Back to top

Contributing

See CONTRIBUTING.md for development setup, validation commands, and contribution guidelines.

Back to top

License

MIT

Back to top