Update readme.md
This commit is contained in:
130
README.md
130
README.md
@@ -1,54 +1,112 @@
|
|||||||
# pobsync
|
# pobsync
|
||||||
|
|
||||||
`pobsync` is a pull-based backup tool for sysadmins.
|
`pobsync` is a pull-based backup tool that runs on a central backup server and pulls data from remote servers via rsync over SSH.
|
||||||
It creates rsync-based snapshots with hardlinking (`--link-dest`) and stores them centrally on a backup server.
|
|
||||||
|
|
||||||
Backups are pulled over SSH, not pushed, and are designed to be run from cron or manually.
|
Key points:
|
||||||
|
|
||||||
* * *
|
- All backup data lives on the backup server.
|
||||||
## Design overview
|
- Snapshots are rsync-based and use hardlinking (--link-dest) for space efficiency.
|
||||||
|
- Designed for scheduled runs (cron) and manual runs.
|
||||||
|
- Minimal external dependencies (currently only PyYAML).
|
||||||
|
|
||||||
* Runtime, config, logs and state live under `/opt/pobsync`
|
|
||||||
* Backup data itself is stored under a configurable `backup_root` (e.g. `/srv/backups`)
|
|
||||||
* Two snapshot types:
|
|
||||||
* scheduled
|
|
||||||
Participates in retention pruning (daily / weekly / monthly / yearly)
|
|
||||||
* manual
|
|
||||||
Kept outside the scheduled prune chain, defaults to hardlinking from the latest scheduled snapshot
|
|
||||||
* Minimal dependencies (currently only `PyYAML`)
|
|
||||||
|
|
||||||
* * *
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
* Python 3.11+
|
On the backup server:
|
||||||
* `rsync`
|
|
||||||
* `ssh`
|
|
||||||
* Root or sudo access on the backup server
|
|
||||||
* SSH keys already configured between backup server and remotes
|
|
||||||
|
|
||||||
* * *
|
- Python 3
|
||||||
## Installation (canonical runtime under /opt/pobsync, no venv)
|
- rsync
|
||||||
|
- ssh
|
||||||
|
- SSH key-based access from the backup server to remotes
|
||||||
|
|
||||||
This assumes you are installing as root or via sudo.
|
## Canonical installation (no venv, repo used only for deployment)
|
||||||
|
|
||||||
1) Clone the repo
|
This project uses a simple and explicit deployment model:
|
||||||
|
|
||||||
git clone https://code.hosting.hippogrief.nl/hippogrief/pobsync.git
|
- The git clone is only used as a deployment input (and later for updates).
|
||||||
cd pobsync
|
- Runtime code is deployed into /opt/pobsync/lib.
|
||||||
|
- The canonical entrypoint is /opt/pobsync/bin/pobsync.
|
||||||
|
|
||||||
2) Deploy the runtime into `/opt/pobsync` (copies code into `/opt/pobsync/lib` and installs `/opt/pobsync/bin/pobsync`)
|
### Install
|
||||||
|
|
||||||
sudo ./scripts/deploy --prefix /opt/pobsync
|
```git clone https://code.hosting.hippogrief.nl/hippogrief/pobsync.git
|
||||||
|
cd pobsync
|
||||||
|
sudo ./scripts/deploy --prefix /opt/pobsync
|
||||||
|
|
||||||
3) Initialize runtime layout and global config
|
pobsync install --backup-root /mnt/backups/pobsync (install default configurations)
|
||||||
|
pobsync doctor (check if the installation was done correctly)
|
||||||
|
```
|
||||||
|
|
||||||
sudo /opt/pobsync/bin/pobsync install --backup-root /mnt/backups/pobsync
|
### Update
|
||||||
sudo /opt/pobsync/bin/pobsync doctor
|
|
||||||
|
|
||||||
## Updating
|
```
|
||||||
|
cd /path/to/pobsync
|
||||||
|
git pull
|
||||||
|
|
||||||
cd /path/to/pobsync
|
sudo ./scripts/deploy --prefix /opt/pobsync
|
||||||
git pull
|
sudo /opt/pobsync/bin/pobsync doctor
|
||||||
sudo ./scripts/deploy --prefix /opt/pobsync
|
```
|
||||||
sudo /opt/pobsync/bin/pobsync doctor
|
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
Global configuration is stored at:
|
||||||
|
|
||||||
|
- /opt/pobsync/config/global.yaml
|
||||||
|
|
||||||
|
Per-host configuration files are stored at:
|
||||||
|
|
||||||
|
- /opt/pobsync/config/hosts/<host>.yaml
|
||||||
|
|
||||||
|
## Some useful commands to get you started
|
||||||
|
|
||||||
|
Create a new host configuration:
|
||||||
|
|
||||||
|
`pobsync init-host <host>`
|
||||||
|
|
||||||
|
List configured remotes:
|
||||||
|
|
||||||
|
`pobsync list-remotes`
|
||||||
|
|
||||||
|
Inspect the effective configuration for a host:
|
||||||
|
|
||||||
|
`pobsync show-config <host>`
|
||||||
|
|
||||||
|
## Running backups
|
||||||
|
|
||||||
|
Run a scheduled backup for a host:
|
||||||
|
|
||||||
|
`pobsync run-scheduled <host>`
|
||||||
|
|
||||||
|
Optionally apply retention pruning after the run:
|
||||||
|
|
||||||
|
`pobsync run-scheduled <host> --prune`
|
||||||
|
|
||||||
|
## Scheduling (cron)
|
||||||
|
|
||||||
|
Create a cron schedule (writes into /etc/cron.d/pobsync by default):
|
||||||
|
|
||||||
|
`pobsync schedule create <host> --daily 02:15 --prune`
|
||||||
|
|
||||||
|
List existing schedules:
|
||||||
|
|
||||||
|
`pobsync schedule list`
|
||||||
|
|
||||||
|
Remove a schedule:
|
||||||
|
|
||||||
|
`pobsync schedule remove <host>`
|
||||||
|
|
||||||
|
Cron output is redirected to:
|
||||||
|
|
||||||
|
- /var/log/pobsync/<host>.cron.log
|
||||||
|
|
||||||
|
## Development (optional)
|
||||||
|
|
||||||
|
For development purposes you can still use an editable install, this is why pyproject.toml still exists:
|
||||||
|
|
||||||
|
```
|
||||||
|
python3 -m pip install -e .
|
||||||
|
pobsync --help
|
||||||
|
```
|
||||||
|
|
||||||
|
For production use, always use the canonical entrypoint:
|
||||||
|
|
||||||
|
/opt/pobsync/bin/pobsync
|
||||||
|
|||||||
Reference in New Issue
Block a user