commit 9032a18bee5a9244838ab802da1d4007d10b919c
parent bcf5e3f10c4fef64f40beb6ca3a73bcc225c4c54
Author: Javier Sepulveda <javier.sepulveda@uv.es>
Date: Wed, 22 May 2024 11:50:53 +0200
Borgbackup tutorial draft
Diffstat:
4 files changed, 174 insertions(+), 1 deletion(-)
diff --git a/system-administration/borgbackup-tutorial.rst b/system-administration/borgbackup-tutorial.rst
@@ -0,0 +1,172 @@
+..
+ 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 <http://www.gnu.org/licenses/>
+
+ @author Javier Sepulveda
+
+Borgbackup tutorial
+###################
+
+.. image:: images/borg-logo.png
+ :width: 440
+ :height: 173
+ :alt: borgbackup-logo
+
+Get help
+==========
+borg help
+
+`Borg official documentation <https://borgbackup.readthedocs.io/en/stable/index.html>`_
+
+
+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.
+
+
+
+
diff --git a/system-administration/images/borg-logo.png b/system-administration/images/borg-logo.png
Binary files differ.
diff --git a/system-administration/index.rst b/system-administration/index.rst
@@ -24,3 +24,4 @@ System Administration tutorials
lego-certificates
taler-monitoring-infrastructure
+ borgbackup-tutorial
diff --git a/system-administration/lego-certificates.rst b/system-administration/lego-certificates.rst
@@ -21,7 +21,7 @@
:alt: lego logo
What is Lego
-============
+############
Let's Encrypt client and ACME library written in Go.
