improve documentation

README.md

@@ -43,18 +43,70 @@ This architecture is as secure as SSH, Rsync, chroot and iptables are.
 
 See the [installation guide](docs/install.md) for instructions.
 
+## Server-side usage
+
+See [docs/usage.md](docs/usage.md).
+
+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"
+~~~
+
+~~~
+git clone https://gitea.evolix.org/evolix/evobackup.git
+cd evobackup
+man ./docs/bkctld.8
+~~~
+
+#### Client-side usage
+
+As bkctld creates a dedicated SSH server, everything that connects over SSH can push files to the jail (Rsync, SFTP…).
+
+Example with Rsync :
+
+~~~
+rsync -av -e "ssh -p SSH_PORT" /home/ root@SERVER_NAME:/var/backup/home/
+~~~
+
+An example synchronization script is present in `zzz_evobackup`,
+clone the evobackup repository and read the **CLIENT CONFIGURATION**
+section of the manual.
+
+
 ## Testing
 
-You can deploy test environments with Vagrant :
+You can manage test environments with Vagrant.
+
+There are 4 preconfigured environments :
+* Debian stetch with ext4
+* Debian stetch with btrfs
+* Debian buster with ext4
+* Debian buster with btrfs
+
+You can start them all with :
 
 ~~~
 vagrant up
 ~~~
 
+… or just the one you want :
+
+~~~
+vagrant up buster-btrfs
+~~~
+
 ### Deployment
 
 Run `vagrant rsync-auto` in a terminal for automatic synchronization of
-your local code with Vagrant VM :
+your local code with Vagrant environments :
 
 ~~~
 vagrant rsync-auto
@@ -77,40 +129,4 @@ vagrant@buster-btrfs $ sudo -i
 root@buster-btrfs # bats /vagrant/test/*.bats
 ~~~
 
-You should shellcheck your bats files, but with shellcheck > 0.4.6, because the 0.4.0 version doesn't support bats syntax.
+You should [shellcheck](https://www.shellcheck.net) your bats files, but with shellcheck > 0.4.6, because the 0.4.0 version doesn't support bats syntax.
-
-## Usage
-
-See [docs/usage.md](docs/usage.md).
-
-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"
-~~~
-
-#### Client configuration
-
-You can backup various systems in the evobackup jails : Linux, BSD,
-Windows, macOS. The only need Rsync or an SFTP client.
-
-~~~
-rsync -av -e "ssh -p SSH_PORT" /home/ root@SERVER_NAME:/var/backup/home/
-~~~
-
-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://gitea.evolix.org/evolix/evobackup.git
-cd evobackup
-man ./docs/bkctld.8
-~~~

bkctld.8

@@ -31,7 +31,7 @@ using
 hard links or BTRFS snapshots.
 (So they can not be affected by the client),
 which backups are kept over time can be configured in the jail's nominal
-.Xr evobackup-incl 5
+.Xr evobackup-incs-policy 5
 configuration file.
 .Pp
 A large enough volume must be mounted on
@@ -131,7 +131,7 @@ He can then create the jail:
 .Ed
 .Pp
 And override the default
-.Xr evobackup-incl 5
+.Xr evobackup-incs-policy 5
 rules
 .Bd -literal -offset indent
 # $EDITOR /etc/evobackup/CLIENT_HOST_NAME
@@ -169,7 +169,7 @@ can be found in the
 .Xr rsync 1 ,
 .Xr ssh-keygen 1 ,
 .Xr bkctld 5 ,
-.Xr evobackup-incl 5 ,
+.Xr evobackup-incs-policy 5 ,
 .Xr chroot 8 ,
 .Xr cron 8 ,
 .Xr sshd 8

bkctld.conf.5

@@ -28,7 +28,7 @@ The following variables may be defined:
 .Bl -tag -width Ds
 .It Va CONFDIR
 Directory where
-.Xr evobackup-incl 5
+.Xr evobackup-incs-policy 5
 files are kept.
 It's default value is
 .Pa /etc/evobackup/ .
@@ -63,5 +63,5 @@ will not automatically update the firewall.
 .El
 .Sh SEE ALSO
 .Xr bash 1 ,
-.Xr evobackup-incl 5 ,
+.Xr evobackup-incs-policy 5 ,
 .Xr bkctld 8

docs/configuration.md

@@ -32,7 +32,7 @@ The following variables may be defined:
 *CONFDIR*
 
 > Directory where
-> evobackup-incl(5)
+> evobackup-incs-policy(5)
 > files are kept.
 > It's default value is
 > */etc/evobackup/*.
@@ -80,7 +80,7 @@ The following variables may be defined:
 # SEE ALSO
 
 bash(1),
-evobackup-incl(5),
+evobackup-incs-policy(5),
 bkctld(8)
 
 OpenBSD 6.4 - December 28, 2018

docs/incrementals.md

@@ -1,8 +1,8 @@
-EVOBACKUP-INCL(5) - File Formats Manual
+evobackup-incs-policy(5) - File Formats Manual
 
 # NAME
 
-**evobackup-incl** - incremental backup configuration
+**evobackup-incs-policy** - incremental backup configuration
 
 # SYNOPSIS
 
@@ -13,7 +13,7 @@ EVOBACKUP-INCL(5) - File Formats Manual
 Located by default in
 */etc/evobackup/*,
 each
-**evobackup-incl**
+**evobackup-incs-policy**
 file is named after the
 bkctld(8)
 backup for which the rules it contains must apply.
@@ -31,9 +31,9 @@ character are comments and are ignored.
 The order of the rules does not matter.
 
 Evobackups that do not have their nominal
-**evobackup-incl**
+**evobackup-incs-policy**
 file use the default rules defined in
-*/usr/share/bkctld/inc.tpl*
+*/usr/share/bkctld/incs-policy.tpl*
 
 # EXAMPLES
 
@@ -75,6 +75,6 @@ Keep backups of the last 4 days and the first day of the last 2 months:
 
 bkctld(8),
 cron(8),
-*/etc/evobackup/tpl/inc.tpl*
+*/etc/evobackup/tpl/incs-policy.tpl*
 
 OpenBSD 6.4 - December 28, 2018

docs/usage.md

@@ -27,14 +27,14 @@ in it's
 chroot(8)
 (using the root account).
 
-Prior backups are stored incrementally outside of the
+Dated copies (_incs_) of the data are stored outside of the
 chroot(8)
 using
 ln(1)
 hard links or BTRFS snapshots.
 (So they can not be affected by the client),
-which backups are kept over time can be configured in the jail's nominal
+Old dated copies (_incs_) are deleted every day according to the jail's policy, configured in
-evobackup-incl(5)
+evobackup-incs-policy(5)
 configuration file.
 
 A large enough volume must be mounted on
@@ -57,7 +57,7 @@ The following operands are available:
 
 > Update an evobackup jail
 
-**remove** **all** | *jailname*
+**remove** \[-f|--force\] **all** | *jailname*
 
 > Remove an evobackup jail
 
@@ -115,11 +115,11 @@ The following operands are available:
 
 **inc**
 
-> Generate incremental backups
+> Generate a dated copy of the jail
 
 **rm**
 
-> Remove old incremental backups
+> Remove old dated copies of the jail
 
 # FILES
 
@@ -128,9 +128,9 @@ The following operands are available:
 > Template for
 > bkctld.conf(5)
 
-*/usr/share/bkctld/incl.tpl*
+*/usr/share/bkctld/incs-policy.tpl*
 
-> Default rules for the incremental backups are stored here.
+> Default rules for the dated copies retention policy.
 
 # EXAMPLES
 
@@ -139,7 +139,7 @@ the backup server administrator will need:
 
 *	The host name of the client system.
 
-*	The public RSA
+*	The public SSH key
 	ssh(1)
 	key for the
 	"root"
@@ -162,7 +162,7 @@ He can then create the jail:
 	# bkctld status <JAIL_NAME>
 
 And override the default
-evobackup-incl(5)
+evobackup-incs-policy(5)
 rules
 
 	# $EDITOR /etc/evobackup/<JAIL_NAME>.d/incs_policy
@@ -195,13 +195,13 @@ can be found in the
 rsync(1),
 ssh-keygen(1),
 bkctld(5),
-evobackup-incl(5),
+evobackup-incs-policy(5),
 chroot(8),
 cron(8),
 sshd(8)
 
 # AUTHORS
 
-Victor Laborie
+Victor Laborie, Jérémy Lecour and others at Evolix
 
 OpenBSD 6.4 - December 27, 2018

evobackup-incs-policy.5

@@ -1,8 +1,8 @@
 .Dd December 28, 2018
-.Dt EVOBACKUP-INCL 5
+.Dt evobackup-incs-policy 5
 .Os
 .Sh NAME
-.Nm evobackup-incl
+.Nm evobackup-incs-policy
 .Nd incremental backup configuration
 .Sh SYNOPSIS
 .D1 +%Y-%m-%d.-%day
@@ -31,7 +31,7 @@ The order of the rules does not matter.
 Evobackups that do not have their nominal
 .Nm
 file use the default rules defined in
-.Pa /usr/share/bkctld/inc.tpl
+.Pa /usr/share/bkctld/incs-policy.tpl
 .Sh EXAMPLES
 Keep today's backup:
 .Bd -literal -offset indent
@@ -76,4 +76,4 @@ Keep backups of the last 4 days and the first day of the last 2 months:
 .Sh SEE ALSO
 .Xr bkctld 8 ,
 .Xr cron 8 ,
-.Pa /etc/evobackup/tpl/inc.tpl
+.Pa /etc/evobackup/tpl/incs-policy.tpl

lib/includes

@@ -366,8 +366,8 @@ setup_jail_config() {
     info "4 - Copie default sshd_config"
     install -m 0640 "${sshd_config_tpl}" "${jail_sshd_config}"
 
-    inctpl="${TPLDIR}/inc.tpl"
+    inctpl="${TPLDIR}/incs-policy.tpl"
-    test -f "${LOCALTPLDIR}/inc.tpl" && inctpl="${LOCALTPLDIR}/inc.tpl"
+    test -f "${LOCALTPLDIR}/incs-policy.tpl" && inctpl="${LOCALTPLDIR}/incs-policy.tpl"
 
     info "5 - Copie default inc configuration"
     jail_incs_policy_file=$(jail_incs_policy_file "${jail_name}")