From ceabbf38d382160ae0b31c34df3b5f41051823f7 Mon Sep 17 00:00:00 2001 From: Axel Burri Date: Sat, 7 Feb 2015 15:53:21 +0100 Subject: [PATCH] documentation: added README.md --- README.md | 253 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 253 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..0b82ddd --- /dev/null +++ b/README.md @@ -0,0 +1,253 @@ +Introduction +============ + +btrbk is a backup tool for btrfs subvolumes, taking advantage of btrfs +specific capabilities to create atomic snapshots and transfer them +incrementally to your backup locations. + +The source and target locations are specified in a config file. This +allows simple setups on a single machine with locally attached backup +disks, as well as handling more complex scenarios on a server +receiving backups from several hosts via ssh. + +Key Features: + +- Atomic snapshots +- Incremental backups +- Backups to multiple destinations +- Transfer via ssh +- Configurable retention policy +- Display file changes between two backups + +btrbk is intended to be run as a cron job. + + +Installation +============ + +btrbk comes as a single executable file (perl script), without the +need of any installation procedures. If you want the package and +man-pages properly installed, follow the instructions below. + +Prerequisites +------------- + +- perl interpreter (probably already installed on your system) +- [Date::Calc] (perl module, probably already installed on your system) +- [btrfs-progs] (Btrfs filesystem utilities) + + [Date::Calc]: http://search.cpan.org/perldoc?Date::Calc + [btrfs-progs]: http://www.kernel.org/pub/linux/kernel/people/kdave/btrfs-progs/ + +Instructions +------------ + +First, [download] the newest stable btrbk source. +Unzip the tarball, go to the btrbk directory and type: + + sudo make install + +This will install the btrbk executable along with the man-pages and +an example configuration file. + + [download]: http://www.digint.ch/download/btrbk/releases + + +Synopsis +======== + +Please consult the [btrbk man-page] provided with this package for a +full description of the command line options. + + [btrbk man-page]: http://www.digint.ch/btrbk/doc/btrbk.html + + +Configuration File +================== + +Before running `btrbk`, you will need to create a config file. You +might want to take a look at the example configuration file provided +with this package: `btrbk.conf.example`. + +When playing around with config-files, it is highly recommended to +check the output using the `dryrun` command before executing the +backups: + + btrbk -c myconfig -v dryrun + +This will read all btrfs information on the source/target filesystems +and show what actions would be performed (without writing anything to +the disks). + + +Example: laptop with usb-disk for backups +----------------------------------------- + +In this example, we assume you have a laptop with: + +- a disk having a btrfs volume mounted as `/mnt/btr_pool`, containing + a subvolume `rootfs` for the root filesystem and a subvolume `home` + for the user data. +- a backup disk having a btrfs volume mounted as `/mnt/btr_backup`, + containing a subvolume `mylaptop` for the incremental backups. + +Retention policy: + +- keep snapshots for 14 days (very handy if you are on the road and + the backup disk is not attached) +- keep monthly backups forever +- keep weekly backups for 10 weeks +- keep daily backups for 20 days + +/etc/btrbk/btrbk-mylaptop.conf: + + snapshot_preserve_daily 14 + snapshot_preserve_weekly 0 + snapshot_preserve_monthly 0 + + target_preserve_daily 20 + target_preserve_weekly 10 + target_preserve_monthly all + + snapshot_dir btrbk_snapshots + + volume /mnt/btr_pool + subvolume rootfs + target send-receive /mnt/btr_backup/mylaptop + + subvolume home + target send-receive /mnt/btr_backup/mylaptop + + +/etc/cron.daily/btrbk: + + #!/bin/bash + /etc/btrbk/btrbk -c /etc/btrbk/btrbk-mylaptop.conf execute + + +- This will create snapshots on a daily basis: + - `/mnt/btr_pool/btrbk_snapshots/rootfs.YYYYMMDD` + - `/mnt/btr_pool/btrbk_snapshots/home.YYYYMMDD` +- And create incremental backups in: + - `/mnt/btr_backup/mylaptop/rootfs.YYYYMMDD` + - `/mnt/btr_backup/mylaptop/home.YYYYMMDD` + +If you want the snapshots to be created even if the backup disk is not +attached (when you're on the road), simply add the following line to +the config: + + snapshot_create_always yes + + +Example: host-initiated backup on fileserver +-------------------------------------------- + +Lets say you have a fileserver at "myserver.mydomain.com" where you +want to create backups of your laptop disk, the config would look like +this: + + ssh_identity /etc/btrbk/ssh/id_rsa + + volume /mnt/btr_pool + subvolume rootfs + target send-receive /mnt/btr_backup/mylaptop + target send-receive ssh://myserver.mydomain.com/mnt/btr_backup/mylaptop + +In addition to the backups on your local usb-disk mounted at +`/mnt/btr_backup/mylaptop`, incremental backups would also be pushed +to `myserver.mydomain.com`. + + +Example: fileserver-initiated backups from several hosts +-------------------------------------------------------- + +If you're a sysadmin and want to trigger backups directly from your +fileserver, the config would be something like: + + ssh_identity /etc/btrbk/ssh/id_rsa + + volume ssh://alpha.mydomain.com/mnt/btr_pool + subvolume rootfs + target send-receive /mnt/btr_backup/alpha + + subvolume home + target send-receive /mnt/btr_backup/alpha + + volume ssh://beta.mydomain.com/mnt/btr_pool + subvolume rootfs + target send-receive /mnt/btr_backup/beta + + subvolume dbdata + target send-receive /mnt/btr_backup/beta + +This will pull backups from alpha/beta.mydomain.com and locally create: + +- `/mnt/btr_backup/alpha/rootfs.YYYYMMDD` +- `/mnt/btr_backup/alpha/home.YYYYMMDD` +- `/mnt/btr_backup/beta/rootfs.YYYYMMDD` +- `/mnt/btr_backup/beta/dbdata.YYYYMMDD` + + +Setting up SSH +============== + +Since btrbk needs root access on the remote side, it is *very +advisable* to take all security precautions you can. Usually backups +are generated periodically without user interaction, so it is not +possible to protect your ssh key with a password. The steps below +shall give you hints on how to secure your ssh server for a backup +scenario. + +btrbk provides a little shell script called "ssh_filter_btrbk.sh", +which only allows sane calls to the /sbin/btrfs command needed for +snapshot creation and send/receive operations. This is how it is used +with ssh: + +**Step 1** (client): Create a ssh key dedicated to btrbk, without password protection: + + ssh-keygen -t rsa -b 2048 -f /etc/btrbk/ssh/id_rsa -C btrbk@mydomain.com -N "" + +**Step 2** (server): Copy the "ssh_filter_btrbk.sh" from the btrbk project to "/root/". + +**Step 3** (server): Add contents of the public key + (/etc/btrbk/ssh/id_rsa.pub) to "/root/.ssh/authorized_keys", + restricting access from a single host: + + from="192.168.0.42",command="/root/ssh_filter_btrbk.sh" ssh-rsa AAAAB3NzaC1...hwumXFRQBL btrbk@mydomain.com + +Now your ssh server allows connections only from 192.168.0.42, and +will only execute commands needed by btrbk. Note that the btrbk +executable is not needed on the remote side, but you will need +"/sbin/btrfs" from the btrfs-progs package. + + +Development +=========== + +Source Code Repository +---------------------- + +The source code for btrbk is managed using Git. Check out the source +like this: + + git clone git://dev.tty0.ch/btrbk.git + + +How to Contribute +----------------- + +Your contributions are welcome! + +If you would like to contribute or found bugs, visit the [btrbk +project page on GitHub](http://github.com/digint/btrbk), or contact +the author via email. + + +License +======= + +btrbk is free software, available under the [GNU General Public +License, Version 3][GPLv3]. + + [GPLv3]: http://www.gnu.org/licenses/gpl.html +