..
This file is part of GNU TALER.
Copyright (C) 2014-2023 Taler Systems SA
TALER is free software; you can redistribute it and/or modify it under the
terms of the GNU Affero General Public License as published by the Free Software
Foundation; either version 2.1, or (at your option) any later version.
TALER is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with
TALER; see the file COPYING. If not, see
@author Javier Sepulveda
Borgbackup tutorial
###################
.. image:: images/borg-logo.png
:width: 440
:height: 173
:alt: borgbackup-logo
Get help
==========
borg help
`Borg official documentation `_
How to install
==============
The easiest way to install the stable version of Borg is by using the APT package manager method,
so you stick to the stable package for your distribution, in our case we use Debian.
.. code-block:: console
# apt install borgbackup
Useful command list to use remotely
======================================
Initiate remote repository. This is somehow really similar of doing a "git init". Borg will create the necessary
files and structure, for storing your future backups.
.. code-block:: console
$ mkdir -p /path/to/repo
$ borg init -e=none usr@srv:/path/to/repo
$ borg init --encryption=repokey usr@srv:/path/to/repo
Send data from your computer to a specif repository
.. code-block:: console
$ borg create --stats --progress --compression lz4 usr@dest:/path/to/repo::name /path/from/origin
List available backups of specific borg repository (a folder):
.. code-block:: console
borg list usr@dest:/path/to/repo
borg list backups@sam.gnunet.org:/home/backups/$folder
Extract the content to your computer of specific backup:
.. code-block:: console
borg extract --progress backups@sam.gnunet.org:/home/backups/weblate::2024-04-09T02:00:00
List the content of a specific backup-name
.. code-block:: console
borg list usr@dest:/path/to/repo::backup-name
Find spefic stuff within a backup without the need of downloading and extracting it
.. code-block:: console
borg list usr@dest:/path/to/repo::backup-name | grep $keyword
Restoring data
=================
.. note::
Note: For restoring, it is always better to do it from origin, and not in the backup server itself.
Please remember this.
.. code-block:: console
$ mkdir $folder
$ cd $folder
$ # Find the concrete backup to restore:
$ borg list usr@dest:/path/repo
$ # Once you have the "name" of the repo
$ # You can check the content, to makes sure it has what you are looking for
$ borg list usr@dest::/remote/path/backupX
$ # Fully extract the backup to destination folder
$ borg extract usr@dest::/remote/path/backupX
$ # Just extract "some" data
$ borg extract usr@dest::/remote/path/backupX path/to/extract/only
$ borg extract --progress backups@sam.gnunet.org:/home/backups/weblate::2023-11-13T11:29:30
Free remote disk space
=========================
Be careful, prune is a potentially dangerous command, it will remove backup archives.
The default of prune is to apply to all archives in the repository unless you restrict its operation to a subset of the archives using --prefix. When using --prefix, be careful to choose a good prefix - e.g. do not use a prefix “foo” if you do not also want to match “foobar”.
It is strongly recommended to always run prune -v --list --dry-run before,
so you will see what it would do without it actually doing anything.
Examples:
# Keep 7 end of day and 4 additional end of week archives.
borg prune -v --list --dry-run --keep-daily=7 --keep-weekly=4 /path/to/repo
# Real (without dry-run, this will remove data)
borg prune -v --list --keep-daily=7 --keep-weekly=4 /path/to/repo
Full example of how to apply borgbackup in a server, to backup specific data
============================================================================
You will find quite a few useful scripts to apply borgbackup in the migration-exercise-stable.git private repository,
and within under the path /taler.net/borgbackup.
The best way and most secure way to use borg is with systemd timers, but it can also be used with a cronjob as usual.
Locations that we use:
-----------------------
Local folder to gather your files temporarily: /home/user/borgbackup
- borgbackup.sh # to send the data, to the borgbackup server
- data.sh # to create .tar files, or dump databases
- borgbackup.service # to execute the borgbackup.sh file
- borgbackup.timer # to execute the .service file periodically
Once you have tested that the data.sh, and the borgbackup.sh are working properly, copy them to /opt/bin/borgbackup.
For the borgbackup.service and borgbackup.timer files, copy them to: /etc/systemd/system/
.. code-block:: console
$ cp borgbackup.service borgbackup.timer /etc/systemd/system/
$ systemctl daemon-reload
$ # Check before the .service file works okay
$ systemctl start borgbackup.service
$ # Use journalctl -u borgbackup to fix any issue
$ systemctl enable --now borgbackup.timer
.. note::
Once you have finished applying borg in server,it is mandatory in the following days,
to check that the system is working properly.
Just do a "borg list usr@dest::/remote/path/backupX", to check if a few backups of the previous days,
are listed.