feat: add external backup on borg

roles/ynh_backup/README-FR.md

-# Rôle Ansible : Yunohost Backup
+# Rôle Ansible : YunoHost Backup
 
 [🇬🇧 English version](README.md)
 
-Sauvegardez [Yunohost](https://yunohost.org/#/) avec Ansible !
+Sauvegardez [YunoHost](https://yunohost.org/#/) avec Ansible !
 
 ## Prérequis
 
-Yunohost doit déjà être installé sur votre serveur.
+YunoHost doit déjà être installé sur votre serveur.
 
 ## Variables du rôle
 
-Les variables par défaut sont disponibles dans `default/main.yml` cependant il est possible de les surcharger selon vos besoins en ...
+Les variables par défaut sont disponibles dans `default/main.yml` cependant il est possible de les surcharger selon vos besoins.
+Nous avons intégré deux systèmes de sauvegardes différents à ce rôle YunoHost :
 
-### Gestion des sauvegardes
+- sauvegardes natives YunoHost en local
+- sauvegardes à distance avec un [depot BorgBackup](https://borgbackup.readthedocs.io/en/stable/)
+
+### Sauvegardes natives YunoHost locales
+
+- Les backups locaux natifs à YunoHost : YunoHost propose son propre système de sauvegardes natif. Il est capable de sauvegarder la configuration YunoHost, les mails (si YunoHost est utilisé en tant que serveur de mails) et les applications installées sur YunoHost. Il est possible de créer et restaurer les sauvegardes depuis l'interface d'administration web ainsi que la ligne de commande en SSH (`yunohost backup`). Les sauvegardes sont disponibles en local et nous avons automatisé le déclenchement de ces sauvegardes par une tâche cron. Plus d'infos [ici](https://yunohost.org/fr/backup).
 
 ```yml
 ynh_backup:
@@ -28,23 +34,55 @@ ynh_backup:
   dest_script: "/usr/bin"
 ```
 
-La tâche _backup_ va permettre de sauvegarder les applications Yunohost ainsi que leurs données grâce à la mise en place d'une tâche cron. Cette sauvegarde utilise celle fournie par [Yunohost](https://yunohost.org/fr/backup) et elle est locale au serveur.
+- `ynh_backup.scheduled` : active la fonctionnalité de sauvegarde des applications YunoHost, mettez la valeur à `True`.
+- `ynh_backup.directory` : le dossier de sauvegarde par défaut est `/home/yunohost.backup/archives` cependant vous pouvez tout à fait choisir de sauvegarder les backups dans un autre dossier grâce à cette variable. Dans ce cas, de manière à pouvoir restaurer les backups depuis l'interface web, YunoHost créé automatiquement un lien symbolique de l'archive créée vers son dossier par défaut.
+- `ynh_backup.scheduled_[hour|minute|weekday|month]`: modifie la planification de la tâche cron. Par défaut, elle se déclenchera tous les jours de l'année à 1 heure du matin. Pour plus d'informations concernant les réglages horaires cron, cet outil peut être utile : <https://crontab.guru/>.
+- `ynh_backup.system` : **obligatoire**. Activez la sauvegarde du système YunoHost en mettant la valeur à `True`.
+- `ynh_backup.apps` : **obligatoire**. Activez la sauvegarde des applications YunoHost en mettant la valeur à `True`.
+
+### Sauvegardes distantes avec BorgBackup
+
+- Les sauvegardes avec [BorgBackup](https://borgbackup.readthedocs.io/en/stable/) et [Borgmatic](https://github.com/witten/borgmatic) : Grâce au rôle Ansible `m3nu.ansible_role_borgbackup` nous pouvons automatiser le processus d'installation et de configuration de BorgBackup sur un serveur YunoHost. Les sauvegardes Borg sont accessibles sur un dépôt Borg local ou distant. Plus d'info sur ce rôle [ici](https://github.com/borgbase/ansible-role-borgbackup)
+
+```yml
+ynh_borg_backup_scheduled: True
+borg_source_directories:
+  - "/data/yunohost"
+borg_repository: "/data/backup/live"
+borg_encryption_passphrase: "PLEASECHANGEME"
+borgmatic_config_name: "borgmatic_ynh_config"
+borgmatic_cron_name: "borgmatic_ynh_cron"
+borg_retention_policy:
+  keep_daily: "4"
+ynh_borg_backup_remote_repo: True
+borg_ssh_keys_src: "files/prd/ssh_keys/ynh_ed25519.vault"
+borg_ssh_keys_dest: "/home/debian/.ssh/ynh_ed25519"
+ynh_ssh_borg_command: "ssh_command: ssh -p 7410 -o StrictHostKeychecking=no -i {{ borg_ssh_keys_dest }}"
+```
+
+- `ynh_borg_backup_scheduled` : Active / désactive la fonctionnalité de sauvegarde avec BorgBackup.
+- `ynh_borg_backup_remote_repo` : Active / désactive la fonctionnalité de sauvegarde sur un dépôt distant BorgBackup (tâches liées à la mise en place des clés SSH). Si vous activez cette fonctionnalité, vous aurez besoin d'utiliser les variables `borg_ssh_keys_src` et `borg_ssh_keys_dest`.
+- `borg_source_directories` : Liste des dossiers source à sauvegarder. Par défaut, il s'agit du dossier contenant toutes les données YunoHost (configuration, applications).
+- `borg_repository` : Chemin complet vers le dépôt Borg. Possibilité de donner une liste de dépôts pour sauvegarder les données dans plusieurs endroits. Par défaut, il s'agit du dépôt `/data/backup/live`.
+- `borg_encryption_passphrase` : **Obligatoire**, mot de passe à utiliser pour la clé de chiffrement du dépôt Borg.
+- `borgmatic_config_name` : **Optionnel**, nom du fichier de configuration Borgmatic.
+- `borgmatic_cron_name` : **Optionnel**, nom du fichier de tâche cron.
+- `borg_retention_policy.keep_[hourly|daily|weekly|monthly]` : Permet de régler finement le nombre d'archives récentes que le dépôt doit garder.
+- `borg_ssh_keys_src` : Chemin où se trouve le couple clé publique / privée SSH sur l'hôte Ansible.
+- `borg_ssh_keys_dest` : Chemin où va être copié la paire de clés SSH sur le serveur YunoHost.
+- `ynh_ssh_borg_command`: **Optionnel**, commande SSH personnalisée lors de l'utilisation de Borg sur un dépôt distant.
 
-- `ynh_backup.scheduled` : active la fonctionnalité de sauvegarde des applications Yunohost, mettez la valeur à `True`.
-- `ynh_backup.directory` : le dossier de sauvegarde par défaut est `/home/yunohost.backup/archives` cependant vous pouvez tout à fait choisir de sauvegarder les backups dans un autre dossier grâce à cette variable. Dans ce cas, de manière à pouvoir restaurer les backups depuis l'interface web, Yunohost créé automatiquement un lien symbolique de l'archive créée vers son dossier par défaut.
-- `ynh_backup.scheduled_[hour|minute|weekday|month]`: modifie la planification de la tâche cron. Par défaut elle se déclenchera tous les jours de l'année à 1 heure du matin. Pour plus d'informations concernant les réglages horaires cron, cet outil peut être utile : <https://crontab.guru/>.
-- `ynh_backup.system` : est obligatoire. Activez la sauvegarde du système Yunohost en mettant la valeur à `True`.
-- `ynh_backup.apps` : est obligatoire. Activez la sauvegarde des applications Yunohost en mettant la valeur à `True`.
+N'hésitez pas à regarder les variables disponibles dans le [rôle](https://github.com/borgbase/ansible-role-borgbackup).
 
 ## Dépendances
 
-Aucune.
+Le rôle `m3nu.ansible_role_borgbackup` sera installé sur la machine exécutant Ansible pour que les tâches liées à Borg fonctionnent. Un fichier `requirements.yml` est à la racine du rôle et va télécharger le rôle (par défaut vers `~/.ansible/roles`).
 
 ## Exemple de Playbook
 
 ```yml
 ---
-- name: Configure Yunohost backups
+- name: Configure YunoHost backups
   hosts: all
   become: True
 

roles/ynh_backup/README.md

-# Ansible Role: Yunohost
+# Ansible Role: YunoHost
 
 [🇫🇷 French version](README-FR.md)
 
-Deploy [Yunohost](https://yunohost.org/#/) with Ansible!
+Deploy [YunoHost](https://yunohost.org/#/) with Ansible!
 
 ## Requirements
 
-Yunohost needs to be installed on your server.
+YunoHost needs to be installed on your server.
 
 ## Role Variables
 
-Default variables are available in `default/main.yml` however it is necessary to override them according to your needs for ...
+The default variables are available in `default/main.yml` however it is possible to override them according to your needs.
+We have integrated two different backup systems to this YunoHost role:
 
-### Backups management
+- YunoHost native local backups
+- Remote backups with a [BorgBackup repository](https://borgbackup.readthedocs.io/en/stable/)
+
+### YunoHost native local backups
+
+YunoHost provides its own native backup system. It is able to back up YunoHost configuration, mails (if YunoHost is used as a mail server) and applications installed on YunoHost. It is possible to create and restore backups from the web administration interface as well as from the command line in SSH (`yunohost backup`). Backups are available locally, and we have automated the triggering of these backups. More info [here](https://yunohost.org/en/backup).
 
 ```yml
 ynh_backup:
@@ -28,23 +34,54 @@ ynh_backup:
   dest_script: "/usr/bin"
 ```
 
-The _backup_ task will allow to backup Yunohost applications and their data by setting up a cron job. This backup uses the one provided by [Yunohost](https://yunohost.org/fr/backup) and it is local to the server.
+- `ynh_backup.scheduled`: to enable the YunoHost applications backup feature, set the value to `True`.
+- `ynh_backup.directory`: the default backup folder is `/home/yunohost.backup/archives` however you can choose to save the backups in another folder with this variable. In this case, in order to be able to restore the backups from the web interface, YunoHost automatically creates a symbolic link from the created archive to its default folder.
+- `ynh_backup.scheduled_[hour|minute|weekday|month]`: modifies the scheduling of the cron task. By default, it will run every day of the year at 1am. For more information about cron time settings, this tool can be useful: <https://crontab.guru/>.
+- `ynh_backup.system`: **mandatory**. Enables automatic backup of the YunoHost system by setting the value to `True`.
+- `ynh_backup.apps`: **mandatory**. Enables automatic backup of YunoHost applications by setting the value to `True`.
+
+### remote backups with YunoHost BorgBackup
+
+- Backups with [BorgBackup](https://borgbackup.readthedocs.io/en/stable/) and [Borgmatic](https://github.com/witten/borgmatic): Thanks to the Ansible role `m3nu.ansible_role_borgbackup` we can automate the installation and configuration process of Borg Backup on a YunoHost server. Borg backups are accessible on a local or a remote Borg repository. More info about this role [here](https://github.com/borgbase/ansible-role-borgbackup).
+
+```yml
+ynh_borg_backup_scheduled: True
+borg_source_directories:
+  - "/data/yunohost"
+borg_repository: "/data/backup/live"
+borg_encryption_passphrase: "PLEASECHANGEME"
+borgmatic_config_name: "borgmatic_ynh_config"
+borgmatic_cron_name: "borgmatic_ynh_cron"
+borg_retention_policy:
+  keep_daily: "4"
+ynh_borg_backup_remote_repo: True
+borg_ssh_keys_src: "files/prd/ssh_keys/ynh_ed25519.vault"
+borg_ssh_keys_dest: "/home/debian/.ssh/ynh_ed25519"
+```
+
+- `ynh_borg_backup_scheduled`: Enable / disable the backup feature with BorgBackup.
+- `ynh_borg_backup_remote_repo`: Enable / disable the backup functionality on a BorgBackup remote repository (tasks related to SSH keys setup). If you enable this feature, then you will need to use `borg_ssh_keys_src` and `borg_ssh_keys_dest` variables. 
+- `borg_source_directories`: List of source folders to backup. By default, this is the folder containing all YunoHost data (configuration, applications).
+- `borg_repository`: Full path to the Borg repository. Possibility to give a list of repositories to save data in several places.
+- `borg_encryption_passphrase` : **Mandatory**, password to use for the Borg repository encryption key.
+- `borgmatic_config_name`: **Optional**, name of the Borgmatic configuration file.
+- `borgmatic_cron_name`: **Optional**, name of the cron task file.
+- `borg_retention_policy.keep_[hourly|daily|weekly|monthly]`: Allows you to fine-tune the number of recent archives the repository should keep.
+- `borg_ssh_keys_src`: Path to the SSH public/private key pair on the Ansible host.
+- `borg_ssh_keys_dest`: Path where the SSH key pair will be copied to the YunoHost server.
+- `ynh_ssh_borg_command`: **Optional**, custom SSH command run when using Borg on a remote repository.
 
-- `ynh_backup.scheduled`: to enable the Yunohost applications backup feature, set the value to `True`.
-- `ynh_backup.directory`: the default backup folder is `/home/yunohost.backup/archives` however you can choose to save the backups in another folder with this variable. In this case, in order to be able to restore the backups from the web interface, Yunohost automatically creates a symbolic link from the created archive to its default folder.
-- `ynh_backup.scheduled_[hour|minute|weekday|month]`: modifies the scheduling of the cron task. By default it will run every day of the year at 1am. For more information about cron time settings, this tool can be useful: <https://crontab.guru/>.
-- `ynh_backup.system` : is mandatory. Enables automatic backup of the Yunohost system by setting the value to `True`.
-- `ynh_backup.apps` : is mandatory. Enables automatic backup of Yunohost applications by setting the value to `True`.
+Feel free to look at the variables available in the [role](https://github.com/borgbase/ansible-role-borgbackup).
 
 ## Dependencies
 
-None.
+The `m3nu.ansible_role_borgbackup` role will be installed on the machine running Ansible for Borg-related tasks to work. A `requirements.yml` file is in the root of the role and will download the role (by default to `~/.ansible/roles`).
 
 ## Example Playbook
 
 ```yml
 ---
-- name: Configure Yunohost backups
+- name: Configure YunoHost backups
   hosts: all
   become: True
 

roles/ynh_backup/defaults/main.yml

@@ -18,7 +18,7 @@
 #                                                                             #
 #-----------------------------------------------------------------------------#
 
-# Variables for backup
+# Variables for local YunoHost backups
 ynh_backup:
   scheduled: False
   # directory: "/data/backup"
@@ -28,3 +28,12 @@ ynh_backup:
   # scheduled_month: "*"
   # system: True
   # apps: True
+
+# Variables for YunoHost BorgBackup
+ynh_borg_backup_scheduled: False
+borg_source_directories:
+  - "/data/yunohost"
+borg_repository: "/data/backup/live"
+borg_init_command: "borgmatic init -c /etc/borgmatic/{{ borgmatic_config_name }} -e repokey --syslog-verbosity 1"
+borg_archive_name_format: "'{hostname}-yunohost-live-data-{now:%Y-%m-%d-%H%M%S}'"
+ynh_borg_backup_remote_repo: False

roles/ynh_backup/tasks/backup.yml

@@ -18,7 +18,7 @@
 #                                                                             #
 #-----------------------------------------------------------------------------#
 
-- name: Create backup folder
+- name: Create backup folder if doesn't already exist
   ansible.builtin.file:
     path: "{{ ynh_backup.directory | default('/home/yunohost.backup/archives') }}"
     state: directory

roles/ynh_backup/tasks/borgbackup.yml

+---
+#-----------------------------------------------------------------------------#
+# ansible-yunohost allows to deploy Yunohost using Ansible                    #
+# Copyright 2021-present Lydra https://www.lydra.fr/                          #
+#                                                                             #
+# this program is free software: you can redistribute it and/or modify        #
+# it under the terms of the GNU General Public License as published by        #
+# the Free Software Foundation, either version 3 of the License, or           #
+# (at your option) any later version.                                         #
+#                                                                             #
+# this program 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 General Public License for more details.                                #
+#                                                                             #
+# You should have received a copy of the GNU General Public License           #
+# along with this program. If not, see <http://www.gnu.org/licenses/>.        #
+#                                                                             #
+#-----------------------------------------------------------------------------#
+- name: Download BorgBackup role on localhost
+  ansible.builtin.command: ansible-galaxy install m3nu.ansible_role_borgbackup,v0.9.0 -p ~/.ansible/roles
+  delegate_to: localhost
+  become: False
+
+- name: run BorgBackup role
+  ansible.builtin.import_role:
+    name: m3nu.ansible_role_borgbackup
+
+- name: Create backup folder for BorgBackup repository
+  ansible.builtin.file:
+    path: "{{ borg_repository }}"
+    state: directory
+    mode: '0750'
+
+- name: Configure host for Borg Remote repository
+  block:
+    - name: deploy ssh public key for BorgBackup
+      ansible.builtin.copy:
+        src: "{{ borg_ssh_keys_src }}.pub"
+        dest: "{{ borg_ssh_keys_dest }}.pub"
+        owner: "root"
+        group: "root"
+        mode: 0600
+
+    - name: deploy ssh private key for BorgBackup
+      ansible.builtin.copy:
+        src: "{{ borg_ssh_keys_src }}"
+        dest: "{{ borg_ssh_keys_dest }}"
+        owner: "root"
+        group: "root"
+        mode: 0600
+  when: ynh_borg_backup_remote_repo
+
+- name: change SSH command in "/etc/borgmatic/{{ borgmatic_config_name }}"
+  ansible.builtin.lineinfile:
+    path: "/etc/borgmatic/{{ borgmatic_config_name }}"
+    regexp: "# ssh_command: ssh -i ~/.ssh/id_ed25519"
+    line: "{{ ynh_ssh_borg_command }}"
+    state: present
+  when: ynh_ssh_borg_command is defined
+
+
+- name: change archive name in "/etc/borgmatic/{{ borgmatic_config_name }}"
+  ansible.builtin.lineinfile:
+    path: "/etc/borgmatic/{{ borgmatic_config_name }}"
+    regexp: "archive_name_format:"
+    line: "    archive_name_format: {{ borg_archive_name_format }}"
+    state: present
+
+- name: Create borg launch script in /usr/local/bin
+  ansible.builtin.copy:
+    content: |
+      #!/bin/bash
+      . /opt/borgmatic/bin/activate
+      borg "$@"
+    dest: /usr/local/bin/borg
+    owner: root
+    group: root
+    mode: "0755"
+
+- name: Initialize a new Borg repository
+  ansible.builtin.command: "{{ borg_init_command }}"

roles/ynh_backup/tasks/main.yml

@@ -23,3 +23,10 @@
   when: ynh_backup.scheduled
   tags:
     - backup
+
+- name: Use Borg Backup with YunoHost
+  ansible.builtin.include_tasks: borgbackup.yml
+  when: ynh_borg_backup_scheduled
+  tags:
+    - backup
+    - borg