From 3af8ac1510dfc467c150aa408e08e307d4eafc35 Mon Sep 17 00:00:00 2001 From: Patrick Marchand Date: Wed, 2 Jan 2019 12:20:41 -0500 Subject: [PATCH] Improved README.md and adjacent files. * Fixed the english in README.md and docs/debian.md * Moved installation instructions from README.md to docs/install.md * Reworked the rest of README.md * Added a few comments to bkctld.conf --- README.md | 98 ++++++++++++++++++++----------------------------- bkctld.conf | 5 ++- docs/debian.md | 5 ++- docs/install.md | 47 ++++++++++++++++++++++++ 4 files changed, 93 insertions(+), 62 deletions(-) create mode 100644 docs/install.md diff --git a/README.md b/README.md index 5f77184..8e7e9c2 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,18 @@ Bkctld (aka evobackup) ========= -Bkctld is a shell script to create and manage a backup server which will -handle the backup of many servers (clients). Licence is AGPLv3. +Bkctld is a shell script that creates and manages a backup server +which can handle the backups of many other servers (clients). It +is licensed under the AGPLv3. -The main principle uses SSH chroot (called "jails" in the FreeBSD -world) for each client to backup. Each client will upload his data every day -using rsync in his chroot (using root account). -Incrementals are stored outside of the chroot using hard links or btrfs snapshots. -(So incrementals are not available for clients). Using this method we can keep tens -of backup of each client securely and not using too much space. +It uses SSH chroots (called "jails" in the FreeBSD world) to sandbox +every clients backups. Each client will upload it's data every day +using rsync in it's chroot (using the root account). Prior backups +are stored incrementally outside of the chroot using hard links or +BTRFS snapshots. (So they can not be affected by the client). + +Using this method, we can keep a large quantity of backups of each +client securely and efficiently. ~~~ Backup server @@ -20,56 +23,23 @@ Server 2 ------ SSH/rsync -------> * tcp/2223 * ************ ~~~ -This method uses standard tools (ssh, rsync, cp -al, btrfs subvolume). EvoBackup -is used for many years by Evolix for back up each day hundreds of servers which - uses many terabytes of data. +This method uses standard tools (ssh, rsync, cp -al, btrfs subvolume) +and has been used for many years by Evolix to backup hundreds of +servers, totaling many terabytes of data, each day. bkctld has +been tested on Debian Jessie and should be compatible with other +Debian versions or derived distributions like Ubuntu. -bkctld was test on Debian Jessie. It can be compatible with other Debian version -or derivated distribution like Ubuntu or Debian Wheezy. - -A big size volume must be mount on /backup, we recommend usage of **btrfs** for -subvolume and snapshot fonctionnality. -This volume can be encrypted by **luks** for security reason. +A large enough volume must be mounted on `/backup`, we recommend +the usage of **BTRFS** so you can use sub-volumes and snapshots. +This volume can also be encrypted with **LUKS**. ## Install -A Debian package is available in Evolix repository +See the [installation guide](docs/install.md) for instructions. -~~~ -echo "http://pub.evolix.net/ jessie/" >> /etc/apt/sources.list -apt update -apt install bkctld -~~~ +## Testing -### Chroot dependency - -Chroot jail use part of this package - -~~~ -apt install bash coreutils sed dash mount rsync openssh-server openssh-sftp-server libc6-i386 libc6 -~~~ - -#### Install cron for incremental backup - -Edit root crontab - -~~~ -crontab -e -~~~ - -Add this ligne - -~~~ -30 10 * * * /usr/sbin/bkctld inc && /usr/sbin/bkctld rm -~~~ - -> **Notes :** -> If you want mutiples backups in a day (1 by hour maximum) you can run `bkctld inc` multiples times -> If you want keep incremental backup **for ever**, you just need don't run `bkctld rm` - -## Test - -You can deploy tests environmments with Vagrant : +You can deploy test environments with Vagrant : ~~~ vagrant up @@ -77,7 +47,8 @@ vagrant up ### Deployment -Launch rsync-auto in a terminal for automatic synchronisation of your local code with Vagrant VM : +Launch rsync-auto in a terminal for automatic synchronization of +your local code with Vagrant VM : ~~~ vagrant rsync-auto @@ -85,7 +56,8 @@ vagrant rsync-auto ### Bats -You can run [bats](https://github.com/sstephenson/bats) test with *test* provisionner : +You can run [bats](https://github.com/sstephenson/bats) tests with +the *test* provision : ~~~ vagrant provision --provision-with test @@ -95,21 +67,31 @@ vagrant provision --provision-with test See [docs/usage.md](docs/usage.md). -Man page, in roff language, can be generated with pandoc : +The man(1) page, in troff(7) language, can be generated with pandoc: ~~~ -pandoc -f markdown -t man usage.md --template default.man -V title=bkctld -V section=8 -V date="$(date '+%d %b %Y')" -V footer="$(git describe --tags)" -V header="bkctld man page" +pandoc -f markdown \ + -t man usage.md \ + --template default.man \ + -V title=bkctld \ + -V section=8 \ + -V date="$(date '+%d %b %Y')" \ + -V footer="$(git describe --tags)" \ + -V header="bkctld man page" ~~~ #### Client configuration -You can save various systems on evobackup jail : Linux, BSD, Windows, MacOSX. Only prequisites is rsync command. +You can save various systems in the evobackup jails : Linux, BSD, +Windows, MacOSX. The only prerequisite is the rsync command. ~~~ rsync -av -e "ssh -p SSH_PORT" /home/ root@SERVER_NAME:/var/backup/home/ ~~~ -An example script is present in zzz_evobackup, clone evobackup repo and read **CLIENT CONFIGURATION** section of the manual. +An example synchronization script is present in `zzz_evobackup`, +clone the evobackup repository and read the **CLIENT CONFIGURATION** +section of the manual. ~~~ git clone https://forge.evolix.org/evobackup.git diff --git a/bkctld.conf b/bkctld.conf index b876241..ddcb872 100644 --- a/bkctld.conf +++ b/bkctld.conf @@ -1,4 +1,5 @@ -# Defaults for bkctld command (evobackup) +# bkctld.conf(5) +# Defaults for bkctld(8) command (evobackup) # sourced by /usr/sbin/bkctld and /etc/init.d/bkctld #CONFDIR='/etc/evobackup' @@ -10,5 +11,5 @@ #SSHD_PID='/var/run/sshd.pid' #SSHD_CONFIG='/etc/ssh/sshd_config' #AUTHORIZED_KEYS='/root/.ssh/authorized_keys' -#FIREWALL_RULES='/etc/firewall.rc.jails' +#FIREWALL_RULES='' #LOGLEVEL=6 diff --git a/docs/debian.md b/docs/debian.md index ddcc1b3..e99b0cf 100644 --- a/docs/debian.md +++ b/docs/debian.md @@ -1,6 +1,7 @@ # Debian Package -**bkctld** package can be build from the **debian** branch of this Git repository with git-buildpackage and sbuild. +The **bkctld** package can be built from the **debian** branch of +this git repository with git-buildpackage and sbuild. ## Dependencies @@ -37,7 +38,7 @@ sbuild-createchroot --include=eatmydata,ccache,gnupg unstable /srv/chroot/sid ht ## Build -You must be in **debian** branch : +You must be in the **debian** branch : ~~~ git checkout debian diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..22d3aed --- /dev/null +++ b/docs/install.md @@ -0,0 +1,47 @@ +# Install + +A Debian package is available in the Evolix repository + +~~~ +echo "http://pub.evolix.net/jessie/" >> /etc/apt/sources.list +apt update +apt install bkctld +~~~ + +Then edit `/etc//bkctld` + +## Chroot dependencies + +The chroot jails depend on these packages + +~~~ +apt install \ + bash \ + coreutils \ + sed \ + dash \ + mount \ + rsync \ + openssh-server \ + openssh-sftp-server \ + libc6-i386 \ + libc6 +~~~ + +## Client dependencies + +The clients only require OpenSSH and rsync. + +### Cron job for incremental backups + +Edit the root crontab + +~~~ +# crontab -e ++ 30 10 * * * /usr/sbin/bkctld inc && /usr/sbin/bkctld rm +~~~ + +## Notes +If you want mutiples backups in a day (1 by hour maximum) you can +run `bkctld inc` multiples times, if you want to keep incremental +backups **for ever**, just don't run `bkctld rm`. \ No newline at end of file