btrfs-pnbackup
Btrfs snapshot backup utility
- Push/pull support via SSH
- Retention
- Email notifications
- Compression of transferred data
- Syslog logging
System dependencies
Required
The following packages have to be available on both source and destination
- bash
- btrfs-progs
The system executing btrfs-backup requires
- python3
Optional
- ssh (for remote push/pull, not required for local operation)
- bash has to be set as the default remote shell for the user running the backup
- lzop (for compression support if desired)
- pv (provides progress indication if installed)
- sendmail (for email notifications if desired)
Installation
pip3 install btrfs-pnbackup
Setup
- when using ssh, public/private key authentication should be set up
Non-root SSH
It is normally assumed that you are sshing to the root user of a remote host. Using a nonroot user requires some extra setup.
- on the machine running btrfs-pnbackup
- create an ssh key pair for the root user (i.e. in /root/.ssh)
- when initing the remote with btrfs-pnbackup, use the user name created on the remote host below
- on the remote host
- create a user for the machine running btrfs-pnbackup to login in to. copy the root users public key created above to the authorized_keys of this new user
- disable password login for the new user
- install backup_root.py in the path of the root user (i.e. /usr/local/sbin/backup_root)
- use visudo to edit and save sudoers in to your system configuration (i.e. /etc/sudoers.d/backup_root)
- copy backup_root.conf to /etc/backup_root.conf. add the user created above to this configruation
- create additional users for other machines running btrfs-pnbackup in your environment
Known limitations
- the destination filesystem has to be mounted without the subvol option, otherwise an error will occur on btrfs receive prompting you to remount with fs tree
- some commands (like update) may not be available for backup jobs created with older versions of btrfs-pnbackup. in this case backup jobs can be recreated using destroy and init. existing snapshots will be kept as long as destroy is not invoked with --purge.
Usage examples
Initialize
Initialize a backup job pulling snapshots of subvolume / on remote host myhost.org to local subvolume /backup/myhost
btrfs-pnbackup init ssh://root@myhost.org:port/ /backup/myhost
Initialize a backup job pushing snapshots of local subvolume / to remote subvolume /backup/myhost on host mybackupserver.org
btrfs-pnbackup init / ssh://root@mybackupserver.org:port/backup/myhost
note that in the ssh:// URL, the username and port part are optional; if not specified, the defaults will be used.
Run
Run a backup job
btrfs-pnbackup run /backup/myhost
Cron
Cronjob performing a pull backup job
# /etc/cron.d/btrfs-pnbackup PATH="/usr/sbin:/usr/bin:/sbin:/bin" 30 2 * * * root btrfs-pnbackup run /backup/myhost
Synopsis and options
usage: btrfs-pnbackup [-h] [-q] [--version] [-v]
{init,destroy,update,run,info,transfer} ...
positional arguments:
{init,destroy,update,run,info,transfer}
init initialize backup job
destroy destroy backup job
update update backup job
run run backup job
info backup job info
purge purge backups according to retention expressions
transfer transfer snapshot
optional arguments:
-h, --help show this help message and exit
-q, --quiet do not log to stdout
--version show program's version number and exit
-v can be specified multiple times to increase verbosity
init
usage: btrfs-pnbackup init [-h] [-sc SOURCE_CONTAINER] [-sr SOURCE_RETENTION]
[-dr DESTINATION_RETENTION] [-c]
source-subvolume destination-subvolume
positional arguments:
source-subvolume source subvolume to backup. local path or ssh url
destination-subvolume
destination subvolume receiving backup snapshots.
local path or ssh url
optional arguments:
-h, --help show this help message and exit
-sc SOURCE_CONTAINER, --source-container SOURCE_CONTAINER
relative path from source to source snapshot container
volume
-sr SOURCE_RETENTION, --source-retention SOURCE_RETENTION
expression defining which source snapshots to
retain/cleanup. can be a static number (of backups) or
more complex expression like "1d:4/d, 1w:daily,
2m:none" literally translating to: "1 day from now
keep 4 backups a day, 1 week from now keep daily
backups, 2 months from now keep none"
-dr DESTINATION_RETENTION, --destination-retention DESTINATION_RETENTION
expression defining which destination snapshots to
retain/cleanup. can be a static number (of backups) or
more complex expression (see --source-retention
argument)
-c, --compress enables compression during transmission. Requires lzop
to be installed on both source and destination
run
usage: btrfs-pnbackup run [-h] [-m [MAIL]] [-li LOG_IDENT]
subvolume [subvolume ...]
positional arguments:
subvolume backup job source or destination subvolume. local path
or SSH url
optional arguments:
-h, --help show this help message and exit
-m [MAIL], --mail [MAIL]
enables email notifications. If an email address is
given, it overrides the default email-recipient
setting in /etc/btrfs-pnbackup.conf
-li LOG_IDENT, --log-ident LOG_IDENT
log ident used for syslog logging, defaults to script
name
update
usage: btrfs-pnbackup update [-h] [-sr SOURCE_RETENTION]
[-dr DESTINATION_RETENTION] [-c]
subvolume [subvolume ...]
positional arguments:
subvolume backup job source or destination subvolume. local path
or SSH url
optional arguments:
-h, --help show this help message and exit
-sr SOURCE_RETENTION, --source-retention SOURCE_RETENTION
expression defining which source snapshots to
retain/cleanup. can be a static number (of backups) or
more complex expression like "1d:4/d, 1w:daily,
2m:none" literally translating to: "1 day from now
keep 4 backups a day, 1 week from now keep daily
backups, 2 months from now keep none"
-dr DESTINATION_RETENTION, --destination-retention DESTINATION_RETENTION
expression defining which destination snapshots to
retain/cleanup. can be a static number (of backups) or
more complex expression (see --source-retention
argument)
-c, --compress enables compression during transmission. Requires lzop
to be installed on both source and destination
-nc, --no-compress disable compression during transmission
info
usage: btrfs-pnbackup info [-h] subvolume [subvolume ...]
positional arguments:
subvolume backup job source or destination subvolume. local path or SSH
url
optional arguments:
-h, --help show this help message and exit
purge
usage: btrfs-pnbackup purge [-h] [-sr SOURCE_RETENTION]
[-dr DESTINATION_RETENTION]
subvolume [subvolume ...]
positional arguments:
subvolume backup job source or destination subvolume. local path
or SSH url
optional arguments:
-h, --help show this help message and exit
-sr SOURCE_RETENTION, --source-retention SOURCE_RETENTION
Optionally override expression defining which source
snapshots to retain/cleanup. can be a static number
(of backups) or more complex expression like "1d:4/d,
1w:daily, 2m:none" literally translating to: "1 day
from now keep 4 backups a day, 1 week from now keep
daily backups, 2 months from now keep none"
-dr DESTINATION_RETENTION, --destination-retention DESTINATION_RETENTION
Optionally override expression defining which
destination snapshots to retain/cleanup. can be a
static number (of backups) or more complex expression
(see --source-retention argument)
destroy
usage: btrfs-pnbackup destroy [-h] [--purge] subvolume [subvolume ...]
positional arguments:
subvolume backup job source or destination subvolume. local path or SSH
url
optional arguments:
-h, --help show this help message and exit
--purge removes all backup snapshots from source and destination
transfer
usage: btrfs-pnbackup transfer [-h] [-c]
source-subvolume destination-subvolume
positional arguments:
source-subvolume source subvolume to transfer. local path or ssh url
destination-subvolume
destination subvolume. local path or ssh url
optional arguments:
-h, --help show this help message and exit
-c, --compress enables compression during transmission. Requires lzop
to be installed on both source and destination