Switch documentation to mdoc(7)

Markdown is not a suitable language for technical documentation.
This commit is contained in:
Patrick Marchand 2019-01-02 13:45:21 -05:00
parent 15819ca867
commit eda30a013c
6 changed files with 606 additions and 153 deletions

179
bkctld.8 Normal file
View File

@ -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 /usr/share/bkctld/bkctld.conf
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

67
bkctld.conf.5 Normal file
View File

@ -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 /usr/share/bkctld/bkctld.conf .
.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

View File

@ -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
*/usr/share/bkctld/bkctld.conf*.
* 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

View File

@ -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
```
Keep yesterday's backup:
```
+%Y-%m-%d.-1day
```
Keep the first day of this month:
```
+%Y-%m-01.-0month
```
Keep the first day of last month:
```
+%Y-%m-01.-1month
```
Keep backups for every 15 days:
```
+%Y-%m-01.-1month
+%Y-%m-15.-1month
```
Keep a backup of the first day of january:
```
+%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
```
# SEE ALSO
bkctld(8),
cron(8),
*/etc/evobackup/tpl/inc.tpl*
OpenBSD 6.4 - December 28, 2018

View File

@ -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 <command> [<args>]
~~~
**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 <jailname>
~~~
**init** *jailname*
Update an evobackup jail or all :
> Create an evobackup jail
~~~
bkctld update <jailname>|all
~~~
**update** **all** | *jailname*
Remove an evobackup jail or all :
> Update an evobackup jail
~~~
bkctld remove <jailname>|all
~~~
**remove** **all** | *jailname*
Start an evobackup jail or all :
> Remove an evobackup jail
~~~
bkctld start <jailname>|all
~~~
**start** **all** | *jailname*
Stop an evobackup jail or all :
> Start an evobackup jail
~~~
bkctld stop <jailname>|all
~~~
**stop** **all** | *jailname*
Reload an evobackup jail or all :
> Stop an evobackup jail
~~~
bkctld reload <jailname>|all
~~~
**reload** **all** | *jailname*
Restart an evobackup jail or all :
> Reload an evobackup jail
~~~
bkctld restart <jailname>|all
~~~
**restart** **all** | *jailname*
Sync an evobackup jail or all.
Second server is defined by $NODE var in /etc/default/bkctld :
> Restart an evobackup jail
~~~
bkctld sync <jailname>|all
~~~
**sync** **all** | *jailname*
Print status of all evobackup jail or one jail :
> Sync an evobackup jail, the mirror server is defined by the
> `$NODE`
> variable in
> */etc/default/bkctld*
~~~
bkctld status [<jailname>]
~~~
**status** \[*jailname*]
Print or set the SSH public key of an evobackup jail :
> Print the status of all jails or only
> \[*jailname*].
~~~
bkctld key <jailname> [<keyfile>]
~~~
**key** *jailname* \[*keyfile*]
Print or set the SSH port of an evobackup jail.
Auto to set next available port (last + 1) :
> Print or set the
> ssh(1)
> public key of an evobackup jail
~~~
bkctld port <jailname> [<ssh_port>|auto]
~~~
**port** *jailname* \[**auto** | *port*]
Print or set allowed IP of an evobackup jail.
All for unrestricted access (default) :
> Print or set the
> ssh(1)
> \[*port*]
> of an evobackup jail.
> Using
> \[**auto**]
> will set it to the next available port.
~~~
bkctld ip <jailname> [<ip>|all]
~~~
**ip** *jailname* \[**all** | *address*]
Generate inc of an evobackup jail :
> Print or set the whitelisted IP
> \[*address*]
> for an evobackup jail.
> \[**all**]
> allows unrestricted access and is the default.
~~~
bkctld inc
~~~
**inc**
Remove old inc of an evobackup jail :
> Generate incremental backups
~~~
bkctld rm
~~~
**rm**
> Remove old incremental backups
# FILES
*/usr/share/bkctld/bkctld.conf*
> 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,
* 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 the FIREWALL_RULES variable in [bkctld.conf](configuration.md)
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
```
And override the default [incremental](incrementals.md) rules
And override the default
evobackup-incl(5)
rules
```
# $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/
```
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
```
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

79
evobackup-incl.5 Normal file
View File

@ -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