diff --git a/bkctld.8 b/bkctld.8 new file mode 100644 index 0000000..a162bb8 --- /dev/null +++ b/bkctld.8 @@ -0,0 +1,179 @@ +.Dd December 27, 2018 +.Dt BKCTLD 8 +.Os +.Sh NAME +.Nm bkctld +.Nd tool to manage evobackup jails +.Sh SYNOPSIS +.Nm +.Op Ar operand... +.Sh DESCRIPTION +.Nm +is a shell script that creates and manages a backup server +which can handle the backups of many other servers (clients). +.Pp +It uses +.Xr ssh 1 +and +.Xr chroot 8 +to sandbox every client's backups. +Each client will upload it's data every day +using +.Xr rsync 1 +in it's +.Xr chroot 8 +(using the root account). +.Pp +Prior backups are stored incrementally outside of the +.Xr chroot 8 +using +.Xr 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 +.Xr evobackup-incl 5 +configuration file. +.Pp +A large enough volume must be mounted on +.Pa /backup , +if the filesystem is formatted with BTRFS, +.Nm +will use sub-volumes and snapshots to save space. +.Pp +It's default settings can be overridden in +.Xr bkctld.conf 5 +file. +.Pp +The following operands are available: +.Bl -tag -width Ds +.It Cm init Ar jailname +Create an evobackup jail +.It Cm update Cm all | Ar jailname +Update an evobackup jail +.It Cm remove Cm all | Ar jailname +Remove an evobackup jail +.It Cm start Cm all | Ar jailname +Start an evobackup jail +.It Cm stop Cm all | Ar jailname +Stop an evobackup jail +.It Cm reload Cm all | Ar jailname +Reload an evobackup jail +.It Cm restart Cm all | Ar jailname +Restart an evobackup jail +.It Cm sync Cm all | Ar jailname +Sync an evobackup jail, the mirror server is defined by the +.Ev $NODE +variable in +.Pa /etc/default/bkctld +.It Cm status Op Ar jailname +Print the status of all jails or only +.Op Ar jailname . +.It Cm key Ar jailname Op Ar keyfile +Print or set the +.Xr ssh 1 +public key of an evobackup jail +.It Cm port Ar jailname Op Cm auto | Ar port +Print or set the +.Xr ssh 1 +.Op Ar port +of an evobackup jail. +Using +.Op Cm auto +will set it to the next available port. +.It Cm ip Ar jailname Op Cm all | Ar address +Print or set the whitelisted IP +.Op Ar address +for an evobackup jail. +.Op Cm all +allows unrestricted access and is the default. +.It Cm inc +Generate incremental backups +.It Cm rm +Remove old incremental backups +.El +.Sh FILES +.Bl -tag -width Ds +.It Pa /etc/default/bkctld +Template for +.Xr bkctld.conf 5 +.It Pa /usr/share/bkctld/incl.tpl +Default rules for the incremental backups are stored here. +.El +.Sh EXAMPLES +Before creating a jail and backing up a client, +the backup server administrator will need: +.Bl -bullet +.It +The host name of the client system. +.It +The public RSA +.Xr ssh 1 +key for the +.Dq root +user of the client system, +it is recommended the private key be password-less if automation is desired. +.It +The IPv4 address of the client system is needed +if the administrator wishes to maintain a whitelist, +see +.Va FIREWALL_RULES +in +.Xr bkctld.conf 5 +.El +.Pp +He can then create the jail: +.Bd -literal -offset indent +# bkctld init CLIENT_HOST_NAME +# bkctld key CLIENT_HOST_NAME /root/CLIENT_HOST_NAME.pub +# bkctld ip CLIENT_HOST_NAME CLIENT_IP_ADDRESS +# bkctld start CLIENT_HOST_NAME +# bkctld status CLIENT_HOST_NAME +.Ed +.Pp +And override the default +.Xr evobackup-incl 5 +rules +.Bd -literal -offset indent +# $EDITOR /etc/evobackup/CLIENT_HOST_NAME +.Ed +.Pp +To sync itself, +the client server will need to install +.Xr rsync 1 . +It can then be run manually: +.Bd -literal -offset indent +# rsync -av -e "ssh -p JAIL_PORT" /home/ root@BACKUP_SERVER:/var/backup/home/ +.Ed +.Pp +If a more automated setup is required, +a script can be written in any programming language. +In this case, +it may be useful to validate the backup server's identity before hand. +.Bd -literal -offset indent +# ssh -p JAIL_PORT BACKUP_SERVER +.Ed +.Pp +A +.Xr bash 1 +example to be run under the +.Dq root +user's +.Xr crontab 5 +can be found in the +.Lk https://gitea.evolix.org/evolix/evobackup/src/branch/master/zzz_evobackup "source repository" +.\" .Sh EXIT STATUS +.\" For sections 1, 6, and 8 only. +.\" .Sh DIAGNOSTICS +.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. +.Sh SEE ALSO +.Xr rsync 1 , +.Xr ssh-keygen 1 , +.Xr bkctld 5 , +.Xr evobackup-incl 5 , +.Xr chroot 8 , +.Xr cron 8 , +.Xr sshd 8 +.Sh AUTHORS +.An Victor Laborie +.\" .Sh CAVEATS +.\" .Sh BUGS \ No newline at end of file diff --git a/bkctld.conf.5 b/bkctld.conf.5 new file mode 100644 index 0000000..3e44bd3 --- /dev/null +++ b/bkctld.conf.5 @@ -0,0 +1,67 @@ +.Dd December 28, 2018 +.Dt BKCTLD.CONF 5 +.Os +.Sh NAME +.Nm bkctld.conf +.Nd configuration file for +.Xr bkctld 8 +.Sh SYNOPSIS +.D1 name=[value] +.Sh DESCRIPTION +The +.Nm +file contains variables that override the behavior of the +.Xr bkctld 8 +script. +By default, it is located at +.Pa /etc/default/bkctld . +.Pp +Each line must be a valid +.Xr bash 1 +variable definition. +Lines beginning with the +.Sq # +character are comments and are ignored. +The order of the definitions does not matter. +.Pp +The following variables may be defined: +.Bl -tag -width Ds +.It Va CONFDIR +Directory where +.Xr evobackup-incl 5 +files are kept. +It's default value is +.Pa /etc/evobackup/ . +.It Va JAILDIR +Directory where the jails are stored, +it is recommended that this be inside a BTRFS file system. +It's default value is +.Pa /backup/jails/ . +.It Va INCDIR +Directory where incremental backups are stored, +it is recommended that this be inside a BTRFS file system. +It's default value is +.Pa /backup/incs/ . +.It Va TPLDIR +Directory where the default configuration files are stored. +It's default value is +.Pa /usr/share/bkctld/ . +.It Va LOCALTPLDIR +Directory where custom configuration files are stored. +It's default is +.Pa /usr/local/share/bkctld/ . +.It Va LOGLEVEL +Defines the amount of information to log, follows the same scale as in +.In syslog.h +and defaults to 6. +.It Va FIREWALL_RULES +Configuration file containing the firewall rules that govern jail access. +This file must be sourced by your firewall. +It does not have a default value and, if unset, +.Xr bkctld 8 +will not automatically update the firewall. +.El +.Sh SEE ALSO +.Xr bash 1 , +.Xr evobackup-incl 5 , +.Xr bkctld 8 diff --git a/docs/configuration.md b/docs/configuration.md index 8045a6c..7b9456e 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,20 +1,86 @@ -# CONFIGURATION VARS +BKCTLD.CONF(5) - File Formats Manual -bkctld configuration has to be set in /etc/default/bkctld file. +# NAME -## REQUIREDS VARS +**bkctld.conf** - configuration file for +bkctld(8) -Default required vars are defined in bkctld script. Alter them to override default values. +# SYNOPSIS -* CONFDIR (default: /etc/evobackup) : Dir where incremental backup is configured. See INCS CONFIGURATION section for details. -* JAILDIR (default : /backup/jails) : Dir for jail's root dir. BTRFS recommended. -* INCDIR (default : /backups/incs) : Dir where incremental backup is stored. BTRFS recommended. -* TPLDIR (default : /usr/share/bkctld) : Dir where jail template file is stored. -* LOCALTPLDIR (default : /usr/local/share/bkctld) : Dir for surcharge jail templates. -* LOGLEVEL (default : 6) : Define loglevel, based on syslog severity level. +> name=\[value] -## OPTIONALS VARS +# DESCRIPTION -Optionnals vars are no default value. No set them desactivate correspondant fonctionnality. +The +**bkctld.conf** +file contains variables that override the behavior of the +bkctld(8) +script. +By default, it is located at +*/etc/default/bkctld*. -* FIREWALL_RULES (default: no firewall auto configuration) : Configuration file were firewall was configured to allow jail access. This file must be sourced by your firewall configuration tool. +Each line must be a valid +bash(1) +variable definition. +Lines beginning with the +'#' +character are comments and are ignored. +The order of the definitions does not matter. + +The following variables may be defined: + +*CONFDIR* + +> Directory where +> evobackup-incl(5) +> files are kept. +> It's default value is +> */etc/evobackup/*. + +*JAILDIR* + +> Directory where the jails are stored, +> it is recommended that this be inside a BTRFS file system. +> It's default value is +> */backup/jails/*. + +*INCDIR* + +> Directory where incremental backups are stored, +> it is recommended that this be inside a BTRFS file system. +> It's default value is +> */backup/incs/*. + +*TPLDIR* + +> Directory where the default configuration files are stored. +> It's default value is +> */usr/share/bkctld/*. + +*LOCALTPLDIR* + +> Directory where custom configuration files are stored. +> It's default is +> */usr/local/share/bkctld/*. + +*LOGLEVEL* + +> Defines the amount of information to log, follows the same scale as in +> <*syslog.h*> +> and defaults to 6. + +*FIREWALL\_RULES* + +> Configuration file containing the firewall rules that govern jail access. +> This file must be sourced by your firewall. +> It does not have a default value and, if unset, +> bkctld(8) +> will not automatically update the firewall. + +# SEE ALSO + +bash(1), +evobackup-incl(5), +bkctld(8) + +OpenBSD 6.4 - December 28, 2018 diff --git a/docs/incrementals.md b/docs/incrementals.md index 9cd3c9d..046fc7d 100644 --- a/docs/incrementals.md +++ b/docs/incrementals.md @@ -1,63 +1,80 @@ -# INCS CONFIGURATION +EVOBACKUP-INCL(5) - File Formats Manual -Located by default in /etc/evobackup/, each incl.tpl file is named -after the EvoBackup for which the rules it contains must apply. +# NAME -The rules it defines decide which incremental backups are kept when -running `bkctl rm` +**evobackup-incl** - incremental backup configuration -Each line defines a single rule. The first part of the rule describes -when the backup was taken, the second part decides how long to keep -it. Lines beginning with the # character are comments and are -ignored. The order of the rules does not matter. +# SYNOPSIS -Evobackups that do not have their nominal incl.tpl file use the -default rules defined in /usr/share/bkctld/inc.tpl +> \+%Y-%m-%d.-%day + +# DESCRIPTION + +Located by default in +*/etc/evobackup/*, +each +**evobackup-incl** +file is named after the +bkctld(8) +backup for which the rules it contains must apply. + +The rules it defines decide which incremental backups are kept when running + + # bkctld rm + +Each line defines a single rule. +The first part of the rule describes when the backup was taken, +the second part decides how long to keep it. +Lines beginning with the +'#' +character are comments and are ignored. +The order of the rules does not matter. + +Evobackups that do not have their nominal +**evobackup-incl** +file use the default rules defined in +*/usr/share/bkctld/inc.tpl* + +# EXAMPLES Keep today's backup: -``` -+%Y-%m-%d.-0day -``` + +%Y-%m-%d.-0day Keep yesterday's backup: -``` -+%Y-%m-%d.-1day -``` + +%Y-%m-%d.-1day Keep the first day of this month: -``` -+%Y-%m-01.-0month -``` + +%Y-%m-01.-0month Keep the first day of last month: -``` -+%Y-%m-01.-1month -``` + +%Y-%m-01.-1month Keep backups for every 15 days: -``` -+%Y-%m-01.-1month -+%Y-%m-15.-1month -``` + +%Y-%m-01.-1month + +%Y-%m-15.-1month Keep a backup of the first day of january: -``` -+%Y-01-01.-1month -``` + +%Y-01-01.-1month Keep backups of the last 4 days and the first day of the last 2 months: -``` -+%Y-%m-%d.-0day -+%Y-%m-%d.-1day -+%Y-%m-%d.-2day -+%Y-%m-%d.-3day -+%Y-%m-01.-0month -+%Y-%m-01.-1month -``` \ No newline at end of file + +%Y-%m-%d.-0day + +%Y-%m-%d.-1day + +%Y-%m-%d.-2day + +%Y-%m-%d.-3day + +%Y-%m-01.-0month + +%Y-%m-01.-1month + +# SEE ALSO + +bkctld(8), +cron(8), +*/etc/evobackup/tpl/inc.tpl* + +OpenBSD 6.4 - December 28, 2018 diff --git a/docs/usage.md b/docs/usage.md index f67ca1d..29c4589 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,162 +1,207 @@ +BKCTLD(8) - System Manager's Manual + # NAME -bkctld - tool to manage evobackup jail +**bkctld** - tool to manage evobackup jails # SYNOPSIS -~~~ -bkctld [] -~~~ +**bkctld** +\[*operand...*] # DESCRIPTION -bkctld is a shell script that creates and manages a backup server +**bkctld** +is a shell script that creates and manages a backup server which can handle the backups of many other servers (clients). -It uses OPENSSH and chroot's to sandbox every client's backups. -Each client will upload it's data every day using rsync in it's chroot + +It uses +ssh(1) +and +chroot(8) +to sandbox every client's backups. +Each client will upload it's data every day +using +rsync(1) +in it's +chroot(8) (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). Which backups are kept over time can be configured in the jail's nominal [incl.tpl](incrementals.md) configuration file. A large enough volume must be mounted on `/backup`, if the filesystem is formatted -with BTRFS, bkctld will use sub-volumes and snapshots to save space. +Prior backups are stored incrementally 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 +evobackup-incl(5) +configuration file. -It's default settings can be overridden in the [configuration file](configuration.md). +A large enough volume must be mounted on +*/backup*, +if the filesystem is formatted with BTRFS, +**bkctld** +will use sub-volumes and snapshots to save space. -# BKCTLD COMMANDS +It's default settings can be overridden in +bkctld.conf(5) +file. -Create an evobackup jail : +The following operands are available: -~~~ -bkctld init -~~~ +**init** *jailname* -Update an evobackup jail or all : +> Create an evobackup jail -~~~ -bkctld update |all -~~~ +**update** **all** | *jailname* -Remove an evobackup jail or all : +> Update an evobackup jail -~~~ -bkctld remove |all -~~~ +**remove** **all** | *jailname* -Start an evobackup jail or all : +> Remove an evobackup jail -~~~ -bkctld start |all -~~~ +**start** **all** | *jailname* -Stop an evobackup jail or all : +> Start an evobackup jail -~~~ -bkctld stop |all -~~~ +**stop** **all** | *jailname* -Reload an evobackup jail or all : +> Stop an evobackup jail -~~~ -bkctld reload |all -~~~ - -Restart an evobackup jail or all : +**reload** **all** | *jailname* -~~~ -bkctld restart |all -~~~ +> Reload an evobackup jail -Sync an evobackup jail or all. -Second server is defined by $NODE var in /etc/default/bkctld : +**restart** **all** | *jailname* -~~~ -bkctld sync |all -~~~ +> Restart an evobackup jail -Print status of all evobackup jail or one jail : +**sync** **all** | *jailname* -~~~ -bkctld status [] -~~~ +> Sync an evobackup jail, the mirror server is defined by the +> `$NODE` +> variable in +> */etc/default/bkctld* -Print or set the SSH public key of an evobackup jail : +**status** \[*jailname*] -~~~ -bkctld key [] -~~~ +> Print the status of all jails or only +> \[*jailname*]. -Print or set the SSH port of an evobackup jail. -Auto to set next available port (last + 1) : +**key** *jailname* \[*keyfile*] -~~~ -bkctld port [|auto] -~~~ +> Print or set the +> ssh(1) +> public key of an evobackup jail -Print or set allowed IP of an evobackup jail. -All for unrestricted access (default) : +**port** *jailname* \[**auto** | *port*] -~~~ -bkctld ip [|all] -~~~ +> Print or set the +> ssh(1) +> \[*port*] +> of an evobackup jail. +> Using +> \[**auto**] +> will set it to the next available port. -Generate inc of an evobackup jail : +**ip** *jailname* \[**all** | *address*] -~~~ -bkctld inc -~~~ +> Print or set the whitelisted IP +> \[*address*] +> for an evobackup jail. +> \[**all**] +> allows unrestricted access and is the default. -Remove old inc of an evobackup jail : +**inc** -~~~ -bkctld rm -~~~ +> Generate incremental backups + +**rm** + +> Remove old incremental backups + +# FILES + +*/etc/default/bkctld* + +> Template for +> bkctld.conf(5) + +*/usr/share/bkctld/incl.tpl* + +> Default rules for the incremental backups are stored here. + +# EXAMPLES -# CLIENT CONFIGURATION Before creating a jail and backing up a client, the backup server administrator will need: -* The host name of the client system. -* The public RSA OpenSSH key for the root user of the client system, -it is recommended the private key be password-less if automation is desired. -* The IPv4 address of the client system is needed -if the administrator wishes to maintain a whitelist, -see the FIREWALL_RULES variable in [bkctld.conf](configuration.md) +* The host name of the client system. + +* The public RSA + ssh(1) + key for the + "root" + user of the client system, + it is recommended the private key be password-less if automation is desired. + +* The IPv4 address of the client system is needed + if the administrator wishes to maintain a whitelist, + see + *FIREWALL\_RULES* + in + bkctld.conf(5) He can then create the jail: -``` -# bkctld init CLIENT_HOST_NAME -# bkctld key CLIENT_HOST_NAME /root/CLIENT_HOST_NAME.pub -# bkctld ip CLIENT_HOST_NAME CLIENT_IP_ADDRESS -# bkctld start CLIENT_HOST_NAME -# bkctld status CLIENT_HOST_NAME -``` + # bkctld init CLIENT_HOST_NAME + # bkctld key CLIENT_HOST_NAME /root/CLIENT_HOST_NAME.pub + # bkctld ip CLIENT_HOST_NAME CLIENT_IP_ADDRESS + # bkctld start CLIENT_HOST_NAME + # bkctld status CLIENT_HOST_NAME -And override the default [incremental](incrementals.md) rules +And override the default +evobackup-incl(5) +rules -``` -# $EDITOR /etc/evobackup/CLIENT_HOST_NAME -``` + # $EDITOR /etc/evobackup/CLIENT_HOST_NAME -To sync itself, the client server will need to install rsync. +To sync itself, +the client server will need to install +rsync(1). It can then be run manually: -``` -# rsync -av -e "ssh -p JAIL_PORT" /home/ root@BACKUP_SERVER:/var/backup/home/ -``` + # rsync -av -e "ssh -p JAIL_PORT" /home/ root@BACKUP_SERVER:/var/backup/home/ If a more automated setup is required, -a script can be written in any programming language. In this case, +a script can be written in any programming language. +In this case, it may be useful to validate the backup server's identity before hand. -``` -# ssh -p JAIL_PORT BACKUP_SERVER -``` + # ssh -p JAIL_PORT BACKUP_SERVER -A bash example to be run under the root user's crontab -can be found in the [source repository](https://gitea.evolix.org/evolix/evobackup/src/branch/master/zzz_evobackup) +A +bash(1) +example to be run under the +"root" +user's +crontab(5) +can be found in the +[source repository](https://gitea.evolix.org/evolix/evobackup/src/branch/master/zzz_evobackup) # SEE ALSO -rsync(1), sshd(8), chroot(8). +rsync(1), +ssh-keygen(1), +bkctld(5), +evobackup-incl(5), +chroot(8), +cron(8), +sshd(8) + +# AUTHORS + +Victor Laborie + +OpenBSD 6.4 - December 27, 2018 diff --git a/evobackup-incl.5 b/evobackup-incl.5 new file mode 100644 index 0000000..48f5453 --- /dev/null +++ b/evobackup-incl.5 @@ -0,0 +1,79 @@ +.Dd December 28, 2018 +.Dt EVOBACKUP-INCL 5 +.Os +.Sh NAME +.Nm evobackup-incl +.Nd incremental backup configuration +.Sh SYNOPSIS +.D1 +%Y-%m-%d.-%day +.Sh DESCRIPTION +Located by default in +.Pa /etc/evobackup/ , +each +.Nm +file is named after the +.Xr bkctld 8 +backup for which the rules it contains must apply. +.Pp +The rules it defines decide which incremental backups are kept when running +.Bd -literal -offset indent +# bkctld rm +.Ed +.Pp +Each line defines a single rule. +The first part of the rule describes when the backup was taken, +the second part decides how long to keep it. +Lines beginning with the +.Sq # +character are comments and are ignored. +The order of the rules does not matter. +.Pp +Evobackups that do not have their nominal +.Nm +file use the default rules defined in +.Pa /usr/share/bkctld/inc.tpl +.Sh EXAMPLES +Keep today's backup: +.Bd -literal -offset indent ++%Y-%m-%d.-0day +.Ed +.Pp +Keep yesterday's backup: +.Bd -literal -offset indent ++%Y-%m-%d.-1day +.Ed +.Pp +Keep the first day of this month: +.Bd -literal -offset indent ++%Y-%m-01.-0month +.Ed +.Pp +Keep the first day of last month: +.Bd -literal -offset indent ++%Y-%m-01.-1month +.Ed +.Pp +Keep backups for every 15 days: +.Bd -literal -offset indent ++%Y-%m-01.-1month ++%Y-%m-15.-1month +.Ed +.Pp +Keep a backup of the first day of january: +.Bd -literal -offset indent ++%Y-01-01.-1month +.Ed +.Pp +Keep backups of the last 4 days and the first day of the last 2 months: +.Bd -literal -offset indent ++%Y-%m-%d.-0day ++%Y-%m-%d.-1day ++%Y-%m-%d.-2day ++%Y-%m-%d.-3day ++%Y-%m-01.-0month ++%Y-%m-01.-1month +.Ed +.Sh SEE ALSO +.Xr bkctld 8 , +.Xr cron 8 , +.Pa /etc/evobackup/tpl/inc.tpl \ No newline at end of file