From 43f540b0a912416da82a5b69a098f1624c0ccd7d Mon Sep 17 00:00:00 2001 From: yalh76 Date: Sun, 13 Mar 2022 17:45:45 +0100 Subject: [PATCH 1/2] Apply last example_ynh --- check_process | 52 +++++++------- doc/.gitkeep | 0 doc/DESCRIPTION.md | 7 ++ doc/DISCLAIMER.md | 143 +++++++++++++++++++++++++++++++++++++++ doc/screenshots/.gitkeep | 0 manifest.json | 8 ++- scripts/_common.sh | 24 +------ scripts/backup | 16 ++++- scripts/install | 23 ++++++- scripts/remove | 38 ++++++++--- scripts/restore | 15 +++- scripts/upgrade | 39 +++++++---- 12 files changed, 290 insertions(+), 75 deletions(-) create mode 100644 doc/.gitkeep create mode 100644 doc/DESCRIPTION.md create mode 100644 doc/DISCLAIMER.md create mode 100644 doc/screenshots/.gitkeep diff --git a/check_process b/check_process index 9358a19..6660ec3 100644 --- a/check_process +++ b/check_process @@ -1,29 +1,31 @@ ;; Test complet -; Manifest - server="dst.domain.tld" - ssh_user="sam" - passphrase="APassphrase" - conf=1 - port=2222 - backup_path=src.domain.tld - data=1 - app="all" - allow_extra_space_use=1 - on_calendar="Daily" - check_on_calendar="*-*-8,15,22 3:15" - check_read_data_on_calendar="*-*-1 3:15" -; Checks - pkg_linter=1 - setup_sub_dir=0 - setup_root=0 - setup_nourl=1 - setup_private=0 - setup_public=0 - upgrade=1 - backup_restore=1 - multi_instance=1 - port_already_use=0 - change_url=0 + ; Manifest + server="dst.domain.tld" + ssh_user="sam" + passphrase="APassphrase" + conf=1 + port=2222 + backup_path=src.domain.tld + data=1 + app="all" + allow_extra_space_use=1 + on_calendar="Daily" + check_on_calendar="*-*-8,15,22 3:15" + check_read_data_on_calendar="*-*-1 3:15" + ; Checks + pkg_linter=1 + setup_sub_dir=0 + setup_root=0 + setup_nourl=1 + setup_private=0 + setup_public=0 + upgrade=1 + # 0.12.0~ynh9 + upgrade=1 from_commit=526944051f68f4149e415be4e862ce3c69d69f18 + backup_restore=1 + multi_instance=1 + port_already_use=0 + change_url=0 ;;; Options Email=restic-ynh@coupouchetty-ramouchetty.fr Notification=down diff --git a/doc/.gitkeep b/doc/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/doc/DESCRIPTION.md b/doc/DESCRIPTION.md new file mode 100644 index 0000000..7f8afa3 --- /dev/null +++ b/doc/DESCRIPTION.md @@ -0,0 +1,7 @@ +## Overview + +A [Restic](https://restic.net/) package for YunoHost (heavily inspired by [the Borg package](https://github.com/YunoHost-Apps/borg_ynh/)). + +Restic is a backup tool that can make local and remote backups. +This package uses restic to make backups to a sftp server. +The package does not handle local backups yet but you can work around that by using the local sftp server as target server (see my comment [here](https://forum.yunohost.org/t/sauvegarde-yunohost-avec-restic/10275/33)). diff --git a/doc/DISCLAIMER.md b/doc/DISCLAIMER.md new file mode 100644 index 0000000..7981df4 --- /dev/null +++ b/doc/DISCLAIMER.md @@ -0,0 +1,143 @@ +## Usage + +If you want to backup your server A onto the server B. + +## Setup Restic app on Server A + +Firstly set up this app on the server A you want to backup: + +``` +$ yunohost app install https://github.com/YunoHost-Apps/restic_ynh +Indicate the server where you want put your backups: serverb.domain.tld +sftp port of your server (default: 22): 2222 +The directory where you want your backup repositories to be created in (default: ./): ./servera.domain.tld +Indicate the ssh user to use to connect on this server: servera +You are now about to define a new user password. The password should be at least 8 characters - though it is good practice to use longer password (i.e. a passphrase) and/or to use various kind of characters (uppercase, lowercase, digits and special characters). +Indicate a strong passphrase, that you will keep preciously if you want to be able to use your backups: +Would you like to backup your YunoHost configuration ? [yes | no] (default: yes): +Would you like to backup mails and user home directory ? [yes | no] (default: yes): +Which apps would you backup (list separated by comma or 'all') ? (default: all): gitlab,blogotext,sogo +Allow backup method to temporarily use more space? [yes | no] (default: yes): +Indicate the backup frequency (see systemd OnCalendar format) (default: *-*-* 0:15:00): *-*-* 0:05 +Indicate the backup check frequency (see systemd OnCalendar format) (default: Sat *-*-8..31 3:15:00): +Indicate the complete backup check frequency (see systemd OnCalendar format) (default: Sun *-*-1..7 3:15:00): +``` + +You can schedule your backup by choosing an other frequency. Some example: + +Monthly : + +Weekly : + +Daily : Daily at midnight + +Hourly : Hourly o Clock + +Sat *-*-1..7 18:00:00 : The first saturday of every month at 18:00 + +4:00 : Every day at 4 AM + +5,17:00 : Every day at 5 AM and at 5 PM + +See here for more info : https://wiki.archlinux.org/index.php/Systemd/Timers#Realtime_timer + +After each invocation an e-mail will be sent to root@yourdomain.tld with the execution log. + +Restic can check backups consistency and verify the actual backed up data has not been modified. +If you use the default values for the backup checks frequencies, a full check will be made on the first day of each month and a simple check will be made on each one of the three remaining weeks of the month. + +At the end of the installation, the app displays the public_key and the user to give to the person who has access to the server B. + +You should now authorize the public key for user `servera` on server B by logging into server B with user `servera` and running: + +``` +mkdir ~/.ssh -p 2>/dev/null +touch ~/.ssh/authorized_keys +chmod u=rw,go= ~/.ssh/authorized_keys +cat << EOPKEY >> ~/.ssh/authorized_keys + +EOPKEY +``` +If you don't find the mail and you don't see the message in the log bar you can find the public_key with this command: +``` +cat /root/.ssh/id_restic_ed25519.pub +``` + +## (Optional) set sftp jail on server B + +To improve security, make sure user `servera` can only do sftp and can only access his home directory on server B. +This is how you would do it on Debian/Ubuntu, otherwise refer to your distribution manual (don't forget to replace `servera` with the real username) + +``` +cat << EOCONFIG >> /etc/ssh/sshd_config +Match User servera + ChrootDirectory %h + ForceCommand internal-sftp + AllowTcpForwarding no + X11Forwarding no +EOCONFIG +service ssh restart +``` + +## Test +At this step your backup should schedule. + +If you want to be sure, you can test it by running on server A: +``` +systemctl start restic.service +``` + +Next you can verify the backup contents by running on server A +``` +restic -r sftp:serverb.domain.tld:servera.domain.tld/auto_conf snapshots +``` + +Replace `auto_conf` with `auto_` if you did not choose to backup configuration but only applications. + +If you want to check the backups consistency: +``` +systemctl start restic_check.service +``` + +If you want to make a complete check of the backups - keep in mind that this reads all the backed up data, it can take some time depending on your target server upload speed (more on this topic in [the Restic documentation](https://restic.readthedocs.io/en/latest/045_working_with_repos.html#checking-integrity-and-consistency)): +``` +systemctl start restic_check_read_data.service +``` + +## Display the apps list to backup + +``` +yunohost app setting restic apps +``` + +## Edit the apps list to backup + +``` +yunohost app setting restic apps -v "nextcloud,wordpress" +``` + +## Launch a backup + +``` +systemctl start restic +``` + +## Launch a backups check + +``` +systemctl start restic_check.service +``` + +## Launch a complete backups check + +WARNING: this will read data from your backups destination server. +It may take a quite long time depending on the target server's internet upload speed and hardware performance. + +``` +systemctl start restic_check_read_data.service +``` + +## Backup on different server, and apply distinct schedule for apps + +You can setup the Restic app several times on the same server so you can backup on several server or manage your frequency backup differently for specific part of your server. + diff --git a/doc/screenshots/.gitkeep b/doc/screenshots/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/manifest.json b/manifest.json index 7b55cd4..fc75ad7 100644 --- a/manifest.json +++ b/manifest.json @@ -8,6 +8,12 @@ }, "version": "0.12.0~ynh9", "url": "https://restic.net/", + "upstream": { + "license": "BSD-2-Clause", + "website": "https://restic.net", + "admindoc": "https://restic.readthedocs.io/en/latest/", + "code": "https://github.com/restic/restic" + }, "license": "BSD-2-Clause", "maintainer": { "name": "Lionel Coupouchetty-Ramouchetty", @@ -15,7 +21,7 @@ "url": "https://gnoobix.net" }, "requirements": { - "yunohost": ">= 3.6.5.3" + "yunohost": ">= 4.3.0" }, "multi_instance": true, "services": [], diff --git a/scripts/_common.sh b/scripts/_common.sh index 542266f..b5e9dd2 100644 --- a/scripts/_common.sh +++ b/scripts/_common.sh @@ -131,26 +131,4 @@ $(yunohost tools diagnosis | grep -B 100 "services:" | sed '/services:/d')" # Send the email to the recipients echo "$mail_message" | $mail_bin -a "Content-Type: text/plain; charset=UTF-8" -s "$mail_subject" "$recipients" -} - -ynh_debian_release () { - lsb_release --codename --short -} - -is_stretch () { - if [ "$(ynh_debian_release)" == "stretch" ] - then - return 0 - else - return 1 - fi -} - -is_jessie () { - if [ "$(ynh_debian_release)" == "jessie" ] - then - return 0 - else - return 1 - fi -} +} \ No newline at end of file diff --git a/scripts/backup b/scripts/backup index bc79252..9e62a26 100755 --- a/scripts/backup +++ b/scripts/backup @@ -6,6 +6,8 @@ # IMPORT GENERIC HELPERS #================================================= +# Keep this path for calling _common.sh inside the execution's context of backup and restore scripts +source ../settings/scripts/_common.sh source /usr/share/yunohost/helpers #================================================= @@ -18,13 +20,19 @@ ynh_abort_if_errors #================================================= # LOAD SETTINGS #================================================= +ynh_print_info --message="Loading installation settings..." export app=$YNH_APP_INSTANCE_NAME export final_path="/opt/yunohost/${app}" +#================================================= +# DECLARE DATA AND CONF FILES TO BACKUP +#================================================= +ynh_print_info --message="Declaring files to be backed up..." + #================================================= -# BACKUP FILES +# BACKUP VARIOUS FILES #================================================= ynh_backup "/usr/local/bin/backup-with-$app" @@ -41,3 +49,9 @@ ssh_dir="/root/.ssh" ynh_backup "${ssh_dir}/id_${app}_ed25519" ynh_backup "${ssh_dir}/id_${app}_ed25519.pub" ynh_backup "${ssh_dir}/config" + +#================================================= +# END OF SCRIPT +#================================================= + +ynh_print_info --message="Backup script completed for $app. (YunoHost will then actually copy those files to the archive)." diff --git a/scripts/install b/scripts/install index 3db6785..f8f3598 100755 --- a/scripts/install +++ b/scripts/install @@ -13,6 +13,9 @@ source /usr/share/yunohost/helpers # MANAGE SCRIPT FAILURE #================================================= +ynh_clean_setup () { + ynh_clean_check_starting +} # Exit if an error occurs during the execution of the script ynh_abort_if_errors @@ -28,20 +31,26 @@ ynh_export server port ssh_user backup_path passphrase on_calendar check_on_cale #================================================= # STORE SETTINGS FROM MANIFEST #================================================= +ynh_script_progression --message="Storing installation settings..." + ynh_save_args server port ssh_user backup_path passphrase on_calendar check_on_calendar check_read_data_on_calendar conf data apps allow_extra_space_use #================================================= # INSTALL RESTIC #================================================= ynh_script_progression --message="Installing restic binary" --weight=7 + install_restic #================================================= # CREATE APP USER #================================================= ynh_script_progression --message="Creating user ${app}" + useradd -m ${app} + ynh_script_progression --message="Configure ${app} user sudoer rights" + cat > /tmp/${app}_sudoer << EOSUDOER ${app} ALL = (root) NOPASSWD: /usr/bin/yunohost*, /bin/journalctl*, /usr/bin/find /etc/yunohost/apps -name backup, ${final_path}/check_method_${app} EOSUDOER @@ -51,6 +60,7 @@ visudo -cf /tmp/${app}_sudoer && mv /tmp/${app}_sudoer /etc/sudoers.d/${app} # ACTIVATE BACKUP METHODS #================================================= ynh_script_progression --message="Activating backup methods" + mkdir -p /etc/yunohost/hooks.d/backup_method mkdir -p /usr/share/yunohost/backup_method @@ -58,6 +68,7 @@ mkdir -p /usr/share/yunohost/backup_method # SETUP THE BACKUP METHOD #================================================= ynh_script_progression --message="Setting up backup methods" + ynh_configure backup_method "/etc/yunohost/hooks.d/backup_method/05-${app}_app" ynh_configure check_method "${final_path}/check_method_${app}" @@ -78,6 +89,7 @@ chown ${app}: "${final_path}/restic_check_log_${app}" # CONFIGURE CRON #================================================= ynh_script_progression --message="Configuring cron" --weight=5 + ynh_configure backup-with-restic "/usr/local/bin/backup-with-${app}" ynh_configure check-restic "${final_path}/check-${app}" chmod +x "/usr/local/bin/backup-with-${app}" @@ -104,12 +116,14 @@ systemctl start ${app}_check_read_data.timer # SET PERMISSIONS ON FINAL PATH #================================================= ynh_script_progression --message="Set permissions on ${final_path}" + chown -R ${app}: ${final_path} #================================================= # SETUP LOGROTATE #================================================= ynh_script_progression --message="Configuring logrotate" + ynh_use_logrotate --logfile=/var/log/restic_backup_${app}.log ynh_use_logrotate --logfile=/var/log/restic_backup_${app}.err ynh_use_logrotate --logfile=/var/log/restic_check_${app}.log @@ -130,6 +144,7 @@ test -f $private_key || ssh-keygen -q -t ed25519 -N "" -f $private_key # GENERATE SSH CONFIG #================================================= ynh_script_progression --message="Generating ssh config for ${app} server ${server}" + grep -q "${app}" ${ssh_dir}/config 2>/dev/null || cat << EOCONF >> ${ssh_dir}/config # begin $app ssh config Host ${server} @@ -145,8 +160,8 @@ EOCONF #================================================= # Display key #================================================= - ynh_script_progression --message="You should now allow the following public key for user ${ssh_user} on server ${server}: + $(cat ${private_key}.pub)" @@ -173,3 +188,9 @@ If you're facing an issue or want to improve this app, please open a new issue i ynh_send_readme_to_admin "$message" "root" ynh_print_ON + +#================================================= +# END OF SCRIPT +#================================================= + +ynh_script_progression --message="Installation of $app completed" diff --git a/scripts/remove b/scripts/remove index 1f0ddf0..9d2927e 100755 --- a/scripts/remove +++ b/scripts/remove @@ -12,20 +12,34 @@ source /usr/share/yunohost/helpers #================================================= # LOAD SETTINGS #================================================= +ynh_script_progression --message="Loading installation settings..." app=$YNH_APP_INSTANCE_NAME export final_path="/opt/yunohost/${app}" +#================================================= +# REMOVE LOGROTATE CONFIGURATION +#================================================= +ynh_script_progression --message="Removing logrotate configuration..." + +# Remove the app-specific logrotate config +ynh_remove_logrotate + #================================================= # REMOVE DEPENDENCIES #================================================= -ynh_script_progression --message="Removing dependencies" --weight=4 +ynh_script_progression --message="Removing dependencies..." --weight=4 + +# Remove metapackage and its dependencies ynh_remove_app_dependencies #================================================= -# REMOVE FILES +# SPECIFIC REMOVE #================================================= -ynh_script_progression --message="Removing files" --weight=2 +# REMOVE VARIOUS FILES +#================================================= +ynh_script_progression --message="Removing various files..." --weight=2 + systemctl stop ${app}.timer systemctl --quiet disable ${app}.timer ynh_remove_systemd_config --service=${app} @@ -42,23 +56,27 @@ ynh_secure_remove "${final_path}/restic_log_${app}" ynh_secure_remove "${final_path}/restic_check_log_${app}" ynh_secure_remove "${final_path}" -#================================================= -# REMOVE LOGROTATE CONFIG -#================================================= -ynh_script_progression --message="Removing logrotate config" -ynh_remove_logrotate - #================================================= # REMOVE SSH CONFIG #================================================= ynh_script_progression --message="Removing ssh config" + ssh_dir="/root/.ssh" sed -e "/begin ${app}/,/end ${app}/{/.*/d}" ${ssh_dir}/config -i || true #================================================= -# REMOVE USER +# GENERIC FINALIZATION +#================================================= +# REMOVE DEDICATED USER #================================================= ynh_script_progression --message="Removing sudoers rights for user ${app}" rm /etc/sudoers.d/${app} + ynh_script_progression --message="Removing ${app} user" --last userdel ${app} + +#================================================= +# END OF SCRIPT +#================================================= + +ynh_script_progression --message="Removal of $app completed" diff --git a/scripts/restore b/scripts/restore index ec36191..fb89b7f 100755 --- a/scripts/restore +++ b/scripts/restore @@ -6,6 +6,7 @@ # IMPORT GENERIC HELPERS #================================================= +# Keep this path for calling _common.sh inside the execution's context of backup and restore scripts source ../settings/scripts/_common.sh source /usr/share/yunohost/helpers @@ -13,16 +14,20 @@ source /usr/share/yunohost/helpers # MANAGE SCRIPT FAILURE #================================================= +ynh_clean_setup () { + ynh_clean_check_starting +} # Exit if an error occurs during the execution of the script ynh_abort_if_errors #================================================= # LOAD SETTINGS #================================================= +ynh_script_progression --message="Loading installation settings..." export app=$YNH_APP_INSTANCE_NAME -export server=$(ynh_app_setting_get $app server) +export server=$(ynh_app_setting_get --app=$app --key=server) export final_path="/opt/yunohost/${app}" @@ -40,14 +45,22 @@ mkdir -p /usr/share/yunohost/backup_method #================================================= # RESTORE FILES #================================================= + ynh_restore #================================================= # ENABLE TIMER #================================================= + systemctl enable --quiet ${app}.timer systemctl enable --quiet ${app}_check.timer systemctl enable --quiet ${app}_check_read_data.timer systemctl start ${app}.timer systemctl start ${app}_check.timer systemctl start ${app}_check_read_data.timer + +#================================================= +# END OF SCRIPT +#================================================= + +ynh_script_progression --message="Restoration completed for $app" diff --git a/scripts/upgrade b/scripts/upgrade index 2c648e5..2db9354 100755 --- a/scripts/upgrade +++ b/scripts/upgrade @@ -12,8 +12,10 @@ source /usr/share/yunohost/helpers #================================================= # LOAD SETTINGS #================================================= +ynh_script_progression --message="Loading installation settings..." export app=$YNH_APP_INSTANCE_NAME + export final_path="/opt/yunohost/${app}" export server=$(ynh_app_setting_get $app server) export port=$(ynh_app_setting_get $app port) @@ -30,18 +32,22 @@ export allow_extra_space_use=$(ynh_app_setting_get $app allow_extra_space_use) #================================================= -# CHECK IF AN UPGRADE IS NEEDED +# CHECK VERSION #================================================= -ynh_check_app_version_changed +ynh_script_progression --message="Checking version..." + +upgrade_type=$(ynh_check_app_version_changed) #================================================= # BACKUP BEFORE UPGRADE THEN ACTIVE TRAP #================================================= +ynh_script_progression --message="Backing up the app before upgrading (may take a while)..." # Backup the current version of the app ynh_backup_before_upgrade ynh_clean_setup () { - # restore it if the upgrade fails + ynh_clean_check_starting + # Restore it if the upgrade fails ynh_restore_upgradebackup } # Exit if an error occurs during the execution of the script @@ -149,15 +155,6 @@ systemctl start ${app}.timer systemctl start ${app}_check.timer systemctl start ${app}_check_read_data.timer -#================================================= -# SETUP LOGROTATE -#================================================= -ynh_script_progression --message="Configuring logrotate" -ynh_use_logrotate --logfile=/var/log/restic_backup_${app}.log -ynh_use_logrotate --logfile=/var/log/restic_backup_${app}.err -ynh_use_logrotate --logfile=/var/log/restic_check_${app}.log -ynh_use_logrotate --logfile=/var/log/restic_check_${app}.err - #================================================= # UPGRADE SSH CONFIG #================================================= @@ -185,4 +182,20 @@ Host ${server} # end $app ssh config EOCONF fi -ynh_script_progression --message="End of upgrade process" --last + +#================================================= +# GENERIC FINALIZATION +#================================================= +# SETUP LOGROTATE +#================================================= +ynh_script_progression --message="Configuring logrotate" +ynh_use_logrotate --logfile=/var/log/restic_backup_${app}.log +ynh_use_logrotate --logfile=/var/log/restic_backup_${app}.err +ynh_use_logrotate --logfile=/var/log/restic_check_${app}.log +ynh_use_logrotate --logfile=/var/log/restic_check_${app}.err + +#================================================= +# END OF SCRIPT +#================================================= + +ynh_script_progression --message="Upgrade of $app completed" From 0c552108bfb7075348ed405a7e4565bb32a53080 Mon Sep 17 00:00:00 2001 From: yunohost-bot Date: Sun, 13 Mar 2022 16:45:50 +0000 Subject: [PATCH 2/2] Auto-update README --- README.md | 41 ++++++----- README_fr.md | 192 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 216 insertions(+), 17 deletions(-) create mode 100644 README_fr.md diff --git a/README.md b/README.md index 7e093f5..5bfd904 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,35 @@ + + # Restic for YunoHost -[![Latest Version](https://img.shields.io/badge/version-0.12.0-green.svg?style=flat)](https://github.com/YunoHost-Apps/restic_ynh/releases) -[![Status](https://img.shields.io/badge/status-testing-yellow.svg?style=flat)](https://github.com/YunoHost-Apps/restic_ynh/milestones) -[![Integration level](https://dash.yunohost.org/integration/restic.svg)](https://dash.yunohost.org/appci/app/restic) -[![GitHub license](https://img.shields.io/badge/license-GPLv3-blue.svg?style=flat)](https://raw.githubusercontent.com/YunoHost-Apps/restic_ynh/master/LICENSE) -[![GitHub issues](https://img.shields.io/github/issues/YunoHost-Apps/restic_ynh.svg?style=flat)](https://github.com/YunoHost-Apps/restic_ynh/issues) - +[![Integration level](https://dash.yunohost.org/integration/restic.svg)](https://dash.yunohost.org/appci/app/restic) ![](https://ci-apps.yunohost.org/ci/badges/restic.status.svg) ![](https://ci-apps.yunohost.org/ci/badges/restic.maintain.svg) [![Install Restic with YunoHost](https://install-app.yunohost.org/install-with-yunohost.svg)](https://install-app.yunohost.org/?app=restic) +*[Lire ce readme en français.](./README_fr.md)* + > *This package allows you to install Restic quickly and simply on a YunoHost server. If you don't have YunoHost, please consult [the guide](https://yunohost.org/#/install) to learn how to install it.* ## Overview +## Overview + A [Restic](https://restic.net/) package for YunoHost (heavily inspired by [the Borg package](https://github.com/YunoHost-Apps/borg_ynh/)). Restic is a backup tool that can make local and remote backups. This package uses restic to make backups to a sftp server. The package does not handle local backups yet but you can work around that by using the local sftp server as target server (see my comment [here](https://forum.yunohost.org/t/sauvegarde-yunohost-avec-restic/10275/33)). + +**Shipped version:** 0.12.0~ynh9 + + + +## Disclaimers / important information + ## Usage If you want to backup your server A onto the server B. @@ -162,19 +173,14 @@ systemctl start restic_check_read_data.service You can setup the Restic app several times on the same server so you can backup on several server or manage your frequency backup differently for specific part of your server. -#### Supported architectures -* x86-64 - [![Build Status](https://ci-apps.yunohost.org/ci/logs/restic%20%28Apps%29.svg)](https://ci-apps.yunohost.org/ci/apps/restic/) -* ARMv8-A - [![Build Status](https://ci-apps-arm.yunohost.org/ci/logs/restic%20%28Apps%29.svg)](https://ci-apps-arm.yunohost.org/ci/apps/restic/) +## Documentation and resources -## Links - - * Report a bug: https://github.com/YunoHost-Apps/restic_ynh/issues - * App website: https://restic.net/ - * Upstream app repository: https://github.com/restic/restic - * YunoHost website: https://yunohost.org/ - ---- +* Official app website: https://restic.net +* Official admin documentation: https://restic.readthedocs.io/en/latest/ +* Upstream app code repository: https://github.com/restic/restic +* YunoHost documentation for this app: https://yunohost.org/app_restic +* Report a bug: https://github.com/YunoHost-Apps/restic_ynh/issues ## Developer info @@ -187,3 +193,4 @@ or sudo yunohost app upgrade restic -u https://github.com/YunoHost-Apps/restic_ynh/tree/testing --debug ``` +**More info regarding app packaging:** https://yunohost.org/packaging_apps \ No newline at end of file diff --git a/README_fr.md b/README_fr.md new file mode 100644 index 0000000..638ae07 --- /dev/null +++ b/README_fr.md @@ -0,0 +1,192 @@ +# Restic pour YunoHost + +[![Niveau d'intégration](https://dash.yunohost.org/integration/restic.svg)](https://dash.yunohost.org/appci/app/restic) ![](https://ci-apps.yunohost.org/ci/badges/restic.status.svg) ![](https://ci-apps.yunohost.org/ci/badges/restic.maintain.svg) +[![Installer Restic avec YunoHost](https://install-app.yunohost.org/install-with-yunohost.svg)](https://install-app.yunohost.org/?app=restic) + +*[Read this readme in english.](./README.md)* +*[Lire ce readme en français.](./README_fr.md)* + +> *Ce package vous permet d'installer Restic rapidement et simplement sur un serveur YunoHost. +Si vous n'avez pas YunoHost, regardez [ici](https://yunohost.org/#/install) pour savoir comment l'installer et en profiter.* + +## Vue d'ensemble + +## Overview + +A [Restic](https://restic.net/) package for YunoHost (heavily inspired by [the Borg package](https://github.com/YunoHost-Apps/borg_ynh/)). + +Restic is a backup tool that can make local and remote backups. +This package uses restic to make backups to a sftp server. +The package does not handle local backups yet but you can work around that by using the local sftp server as target server (see my comment [here](https://forum.yunohost.org/t/sauvegarde-yunohost-avec-restic/10275/33)). + + +**Version incluse :** 0.12.0~ynh9 + + + +## Avertissements / informations importantes + +## Usage + +If you want to backup your server A onto the server B. + +## Setup Restic app on Server A + +Firstly set up this app on the server A you want to backup: + +``` +$ yunohost app install https://github.com/YunoHost-Apps/restic_ynh +Indicate the server where you want put your backups: serverb.domain.tld +sftp port of your server (default: 22): 2222 +The directory where you want your backup repositories to be created in (default: ./): ./servera.domain.tld +Indicate the ssh user to use to connect on this server: servera +You are now about to define a new user password. The password should be at least 8 characters - though it is good practice to use longer password (i.e. a passphrase) and/or to use various kind of characters (uppercase, lowercase, digits and special characters). +Indicate a strong passphrase, that you will keep preciously if you want to be able to use your backups: +Would you like to backup your YunoHost configuration ? [yes | no] (default: yes): +Would you like to backup mails and user home directory ? [yes | no] (default: yes): +Which apps would you backup (list separated by comma or 'all') ? (default: all): gitlab,blogotext,sogo +Allow backup method to temporarily use more space? [yes | no] (default: yes): +Indicate the backup frequency (see systemd OnCalendar format) (default: *-*-* 0:15:00): *-*-* 0:05 +Indicate the backup check frequency (see systemd OnCalendar format) (default: Sat *-*-8..31 3:15:00): +Indicate the complete backup check frequency (see systemd OnCalendar format) (default: Sun *-*-1..7 3:15:00): +``` + +You can schedule your backup by choosing an other frequency. Some example: + +Monthly : + +Weekly : + +Daily : Daily at midnight + +Hourly : Hourly o Clock + +Sat *-*-1..7 18:00:00 : The first saturday of every month at 18:00 + +4:00 : Every day at 4 AM + +5,17:00 : Every day at 5 AM and at 5 PM + +See here for more info : https://wiki.archlinux.org/index.php/Systemd/Timers#Realtime_timer + +After each invocation an e-mail will be sent to root@yourdomain.tld with the execution log. + +Restic can check backups consistency and verify the actual backed up data has not been modified. +If you use the default values for the backup checks frequencies, a full check will be made on the first day of each month and a simple check will be made on each one of the three remaining weeks of the month. + +At the end of the installation, the app displays the public_key and the user to give to the person who has access to the server B. + +You should now authorize the public key for user `servera` on server B by logging into server B with user `servera` and running: + +``` +mkdir ~/.ssh -p 2>/dev/null +touch ~/.ssh/authorized_keys +chmod u=rw,go= ~/.ssh/authorized_keys +cat << EOPKEY >> ~/.ssh/authorized_keys + +EOPKEY +``` +If you don't find the mail and you don't see the message in the log bar you can find the public_key with this command: +``` +cat /root/.ssh/id_restic_ed25519.pub +``` + +## (Optional) set sftp jail on server B + +To improve security, make sure user `servera` can only do sftp and can only access his home directory on server B. +This is how you would do it on Debian/Ubuntu, otherwise refer to your distribution manual (don't forget to replace `servera` with the real username) + +``` +cat << EOCONFIG >> /etc/ssh/sshd_config +Match User servera + ChrootDirectory %h + ForceCommand internal-sftp + AllowTcpForwarding no + X11Forwarding no +EOCONFIG +service ssh restart +``` + +## Test +At this step your backup should schedule. + +If you want to be sure, you can test it by running on server A: +``` +systemctl start restic.service +``` + +Next you can verify the backup contents by running on server A +``` +restic -r sftp:serverb.domain.tld:servera.domain.tld/auto_conf snapshots +``` + +Replace `auto_conf` with `auto_` if you did not choose to backup configuration but only applications. + +If you want to check the backups consistency: +``` +systemctl start restic_check.service +``` + +If you want to make a complete check of the backups - keep in mind that this reads all the backed up data, it can take some time depending on your target server upload speed (more on this topic in [the Restic documentation](https://restic.readthedocs.io/en/latest/045_working_with_repos.html#checking-integrity-and-consistency)): +``` +systemctl start restic_check_read_data.service +``` + +## Display the apps list to backup + +``` +yunohost app setting restic apps +``` + +## Edit the apps list to backup + +``` +yunohost app setting restic apps -v "nextcloud,wordpress" +``` + +## Launch a backup + +``` +systemctl start restic +``` + +## Launch a backups check + +``` +systemctl start restic_check.service +``` + +## Launch a complete backups check + +WARNING: this will read data from your backups destination server. +It may take a quite long time depending on the target server's internet upload speed and hardware performance. + +``` +systemctl start restic_check_read_data.service +``` + +## Backup on different server, and apply distinct schedule for apps + +You can setup the Restic app several times on the same server so you can backup on several server or manage your frequency backup differently for specific part of your server. + + +## Documentations et ressources + +* Site officiel de l'app : https://restic.net +* Documentation officielle de l'admin : https://restic.readthedocs.io/en/latest/ +* Dépôt de code officiel de l'app : https://github.com/restic/restic +* Documentation YunoHost pour cette app : https://yunohost.org/app_restic +* Signaler un bug : https://github.com/YunoHost-Apps/restic_ynh/issues + +## Informations pour les développeurs + +Merci de faire vos pull request sur la [branche testing](https://github.com/YunoHost-Apps/restic_ynh/tree/testing). + +Pour essayer la branche testing, procédez comme suit. +``` +sudo yunohost app install https://github.com/YunoHost-Apps/restic_ynh/tree/testing --debug +ou +sudo yunohost app upgrade restic -u https://github.com/YunoHost-Apps/restic_ynh/tree/testing --debug +``` + +**Plus d'infos sur le packaging d'applications :** https://yunohost.org/packaging_apps \ No newline at end of file