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

@@ -1,15 +1,18 @@
 Bkctld (aka evobackup)
 =========
 
-Bkctld is a shell script to create and manage a backup server which will
+Bkctld is a shell script that creates and manages a backup server
-handle the backup of many servers (clients). Licence is AGPLv3.
+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
+It uses SSH chroots (called "jails" in the FreeBSD world) to sandbox
-world) for each client to backup. Each client will upload his data every day
+every clients backups. Each client will upload it's data every day
-using rsync in his chroot (using root account).
+using rsync in it's chroot (using the root account).  Prior backups
-Incrementals are stored outside of the chroot using hard links or btrfs snapshots.
+are stored incrementally outside of the chroot using hard links or
-(So incrementals are not available for clients). Using this method we can keep tens 
+BTRFS snapshots.  (So they can not be affected by the client). 
-of backup of each client securely and not using too much space.
+
+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 
+This method uses standard tools (ssh, rsync, cp -al, btrfs subvolume)
-is used for many years by Evolix for back up each day hundreds of servers which
+and has been used for many years by Evolix to backup hundreds of
- uses many terabytes of data.
+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
+A large enough volume must be mounted on `/backup`, we recommend
-or derivated distribution like Ubuntu or Debian Wheezy.
+the usage of **BTRFS** so you can use sub-volumes and snapshots.
-
+This volume can also be encrypted with **LUKS**.
-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.
 
 ## Install
 
-A Debian package is available in Evolix repository
+See the [installation guide](docs/install.md) for instructions.
 
-~~~
+## Testing
-echo "http://pub.evolix.net/ jessie/" >> /etc/apt/sources.list
-apt update
-apt install bkctld
-~~~
 
-### Chroot dependency
+You can deploy test environments with Vagrant :
-
-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 :
 
 ~~~
 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

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

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

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`.