Browse Source

Switch documentation to mdoc(7)

Markdown is not a suitable language for technical documentation.
tags/2.0.0
Patrick Marchand 1 year ago
parent
commit
eda30a013c
6 changed files with 606 additions and 153 deletions
  1. +179
    -0
      bkctld.8
  2. +67
    -0
      bkctld.conf.5
  3. +79
    -13
      docs/configuration.md
  4. +55
    -38
      docs/incrementals.md
  5. +147
    -102
      docs/usage.md
  6. +79
    -0
      evobackup-incl.5

+ 179
- 0
bkctld.8 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
- 0
bkctld.conf.5 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

+ 79
- 13
docs/configuration.md 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

+ 55
- 38
docs/incrementals.md 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
```
+%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
```
+%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

+ 147
- 102
docs/usage.md 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.

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.

It's default settings can be overridden in
bkctld.conf(5)
file.

The following operands are available:

**init** *jailname*

> Create an evobackup jail

**update** **all** | *jailname*

It's default settings can be overridden in the [configuration file](configuration.md).
> Update an evobackup jail

# BKCTLD COMMANDS
**remove** **all** | *jailname*

Create an evobackup jail :
> Remove an evobackup jail

~~~
bkctld init <jailname>
~~~
**start** **all** | *jailname*

Update an evobackup jail or all :
> Start an evobackup jail

~~~
bkctld update <jailname>|all
~~~
**stop** **all** | *jailname*

Remove an evobackup jail or all :
> Stop an evobackup jail

~~~
bkctld remove <jailname>|all
~~~
**reload** **all** | *jailname*

Start an evobackup jail or all :
> Reload an evobackup jail

~~~
bkctld start <jailname>|all
~~~
**restart** **all** | *jailname*

Stop an evobackup jail or all :
> Restart an evobackup jail

~~~
bkctld stop <jailname>|all
~~~
**sync** **all** | *jailname*

Reload an evobackup jail or all :
> Sync an evobackup jail, the mirror server is defined by the
> `$NODE`
> variable in
> */etc/default/bkctld*

~~~
bkctld reload <jailname>|all
~~~
Restart an evobackup jail or all :
**status** \[*jailname*]

~~~
bkctld restart <jailname>|all
~~~
> Print the status of all jails or only
> \[*jailname*].

Sync an evobackup jail or all.
Second server is defined by $NODE var in /etc/default/bkctld :
**key** *jailname* \[*keyfile*]

~~~
bkctld sync <jailname>|all
~~~
> Print or set the
> ssh(1)
> public key of an evobackup jail

Print status of all evobackup jail or one jail :
**port** *jailname* \[**auto** | *port*]

~~~
bkctld status [<jailname>]
~~~
> Print or set the
> ssh(1)
> \[*port*]
> of an evobackup jail.
> Using
> \[**auto**]
> will set it to the next available port.

Print or set the SSH public key of an evobackup jail :
**ip** *jailname* \[**all** | *address*]

~~~
bkctld key <jailname> [<keyfile>]
~~~
> Print or set the whitelisted IP
> \[*address*]
> for an evobackup jail.
> \[**all**]
> allows unrestricted access and is the default.

Print or set the SSH port of an evobackup jail.
Auto to set next available port (last + 1) :
**inc**

~~~
bkctld port <jailname> [<ssh_port>|auto]
~~~
> Generate incremental backups

Print or set allowed IP of an evobackup jail.
All for unrestricted access (default) :
**rm**

~~~
bkctld ip <jailname> [<ip>|all]
~~~
> Remove old incremental backups

Generate inc of an evobackup jail :
# FILES

~~~
bkctld inc
~~~
*/usr/share/bkctld/bkctld.conf*

Remove old inc of an evobackup jail :
> Template for
> bkctld.conf(5)

~~~
bkctld rm
~~~
*/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

+ 79
- 0
evobackup-incl.5 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

Loading…
Cancel
Save