evobackup/client
Jérémy Lecour 201b22c145
All checks were successful
gitea/evobackup/pipeline/head This commit looks good
gitea/evobackup/pipeline/tag This commit looks good
Client - Release 24.05.1
2024-05-14 08:19:37 +02:00
..
bin evobackupctl: update LIBDIR when copying the template 2024-05-02 10:18:25 +02:00
lib Client - Release 24.05.1 2024-05-14 08:19:37 +02:00
CHANGELOG.md Client - Release 24.05.1 2024-05-14 08:19:37 +02:00
LICENSE Add AGPL License to client script 2022-05-02 10:27:07 +02:00
README.md mention the Ansible role in the client README 2024-05-02 10:17:46 +02:00
vagrant.yml Vagrant definition for manual tests 2024-01-08 23:01:43 +01:00
Vagrantfile Vagrant definition for manual tests 2024-01-08 23:01:43 +01:00

EvoBackup — the client side

What you install on the servers you want to backup.

Design

backup script

The tip of the iceberg is a script (often called zzz_evobackup because it is executed by cron at the very end of the daily tasks list).

This is where you setup what, how and where to backup on remote server(s).

There are 2 main phases in the backup :

  1. local tasks: everything you want to do locally (save state information, dump databases…).
  2. sync tasks: which data (including what has been prepared in the local phase) you want to send to remote servers.

libraries

The vast majority of the logic is in libraries, to help maintaining them without having to modify the backup script.

They contain mostly dump functions that are called from the backup script.

Those functions contain a lot of code for logging, options parsing, error management, and some code specific to the dump task.

utility script

A scripts named evobackupctl helps initializing a backup jail on remote servers or install the backup script where you want.

Install and update

To install, copy these files :

  • lib/*/usr/local/lib/evobackup
  • bin/evobackupctl/usr/local/bin/evobackupctl

To update, simply overwrite them, since their content should (must?) not be customized locally.

There is also an evobackup-client Ansible role to do this (and some other stuff) automatically.

Usage

backup script

minimal configuration

mail notifications

The absolute minimum you must do is set the MAIL variable to the email address you want to be notified at.

sync tasks

If you want to sync files to a remote server, you have to set the SERVERS variable with at least one host and port. Beware that the default evolix-system sync doesn't sync /home, /srv

If you want to sync files to multiple groups of servers, you can add as many sync sections as you want. A sync section must contain something like this :

# The name of the "sync" (visible in logs)
SYNC_NAME="evolix-system"
# List of servers
SERVERS=(
    host1:port1
    host2:port2
)
# List of paths to include in the sync
RSYNC_INCLUDES=(
    "${rsync_default_includes[@]}"
    /etc
    /root
    /var
)
# List of paths to exclude from the sync
RSYNC_EXCLUDES=(
    "${rsync_default_excludes[@]}"
)
# Actual sync command
sync "${SYNC_NAME}" "SERVERS[@]" "RSYNC_INCLUDES[@]" "RSYNC_EXCLUDES[@]"
local tasks

By default, the local_tasks() function only:

  • executes dump-server-state to put have a saved copy of a lot of information about the server
  • saves a traceroute to some key network endpoints (using the dump_traceroute() function)

You can enable (by uncommenting) as many dump functions as you want.

advanced customization

Since this is a shell script, you can add any bash-compatible code you want. If you do so you should read the libraries code to make sure that you don't overwrite existing functions.

sync tasks

If you don't want to sync files to any remote servers, you can simply replace the content of the sync_tasks() function by a no-op command (:).

RSYNC_INCLUDES and RSYNC_EXCLUDES refer to ${rsync_default_includes[@]} and ${rsync_default_excludes[@]} (defined in the main.sh library) to simplify the configuration. If you want to precisely customize the lists you can remove them and add you own.

local tasks

Existing dump functions (as defined in libraries) are usable as-is, but you can also create your own local custom functions. You have to define them in the backup script (or in a file that you source from the backup script). You should prefix their name with dump_ base your customization on the dump_custom() (documented in the backup script) to keep the boilerplate code (for logging, error management…).

You can customize some values inside the setup_custom(), like the server's hostname, the notification mail subject…

If you want to source libraries from a different path, you can change the LIBDIR variable at the end of the backup script.

utility tool

The command is evobackupctl.

# evobackupctl --help
evobackupctl helps managing evobackup scripts

Options
 -h, --help                  print this message and exit
 -V, --version               print version and exit
     --jail-init-commands    print jail init commands
     --copy-template=PATH    copy the backup template to PATH

# evobackupctl --version
evobackupctl version 24.04

Copyright 2024 Evolix <info@evolix.fr>,
               Jérémy Lecour <jlecour@evolix.fr>.

evobackupctl comes with ABSOLUTELY NO WARRANTY.  This is free software,
and you are welcome to redistribute it under certain conditions.
See the GNU General Public License v3.0 for details.

jail init commands

It prints a list of commands you can execute on remote backup servers to configure a backup "jail".

# evobackupctl --jail-init-commands
Copy-paste those lines on backup server(s) :
----------
SERVER_NAME=example-hostname
SERVER_IP=203.0.113.1
echo 'ssh-ed25519 xxxxxx root@example-hostname' > /root/${SERVER_NAME}.pub
bkctld init ${SERVER_NAME}
bkctld key ${SERVER_NAME} /root/${SERVER_NAME}.pub
bkctld ip ${SERVER_NAME} ${SERVER_IP}
bkctld start ${SERVER_NAME}
bkctld status ${SERVER_NAME}
grep --quiet --extended-regexp "^\s?NODE=" /etc/default/bkctld && bkctld sync ${SERVER_NAME}
----------

copy-template

It copies the backups script template to the path of your choice, nothing more.

# evobackupctl --copy-template /etc/cron.daily/zzz_evobackup
New evobackup script has been saved to '/etc/cron.daily/zzz_evobackup'.
Remember to customize it (mail notifications, backup servers…).