YunoHost/yunohost
1
0
Fork 0
mirror of https://github.com/YunoHost/yunohost.git synced 2024-09-03 20:06:10 +02:00
Code Issues Projects Releases Packages Wiki Activity

helper doc fixes : backup

Browse source
This commit is contained in:
Salamandar 2021-03-03 10:58:34 +01:00
parent e6f3adfa08
commit d69f031d8f
1 changed files with 44 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

71
data/helpers.d/backup
View file

@ -13,13 +13,13 @@ CAN_BIND=${CAN_BIND:-1}
# #
# This helper can be used both in a system backup hook, and in an app backup script # This helper can be used both in a system backup hook, and in an app backup script
# #
# Details: ynh_backup writes SRC and the relative DEST into a CSV file. And it # `ynh_backup` writes `src_path` and the relative `dest_path` into a CSV file, and it
# creates the parent destination directory # creates the parent destination directory
# #
# If DEST is ended by a slash it complete this path with the basename of SRC. # If `dest_path` is ended by a slash it complete this path with the basename of `src_path`.
#
# Example in the context of a wordpress app
# #
# Example in the context of a wordpress app :
# ```
# ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" # ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf"
# # => This line will be added into CSV file # # => This line will be added into CSV file
# # "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/etc/nginx/conf.d/$domain.d/$app.conf" # # "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/etc/nginx/conf.d/$domain.d/$app.conf"
@ -40,26 +40,28 @@ CAN_BIND=${CAN_BIND:-1}
# ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "/conf/" # ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "/conf/"
# # => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/$app.conf" # # => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/$app.conf"
# #
# ```
# #
# How to use --is_big: # How to use `--is_big`:
# --is_big is used to specify that this part of the backup can be quite huge. #
# `--is_big` is used to specify that this part of the backup can be quite huge.
# So, you don't want that your package does backup that part during ynh_backup_before_upgrade. # So, you don't want that your package does backup that part during ynh_backup_before_upgrade.
# In the same way, an user may doesn't want to backup this big part of the app for # In the same way, an user may doesn't want to backup this big part of the app for
# each of his backup. And so handle that part differently. # each of his backup. And so handle that part differently.
# #
# As this part of your backup may not be done, your restore script has to handle it. # As this part of your backup may not be done, your restore script has to handle it.
# In your restore script, use --not_mandatory with ynh_restore_file # In your restore script, use `--not_mandatory` with `ynh_restore_file`
# As well in your remove script, you should not remove those data ! Or an user may end up with # As well in your remove script, you should not remove those data ! Or an user may end up with
# a failed upgrade restoring an app without data anymore ! # a failed upgrade restoring an app without data anymore !
# #
# To have the benefit of --is_big while doing a backup, you can whether set the environement # To have the benefit of `--is_big` while doing a backup, you can whether set the environement
# variable BACKUP_CORE_ONLY to 1 (BACKUP_CORE_ONLY=1) before the backup command. It will affect # variable `BACKUP_CORE_ONLY` to 1 (`BACKUP_CORE_ONLY=1`) before the backup command. It will affect
# only that backup command. # only that backup command.
# Or set the config do_not_backup_data to 1 into the settings.yml of the app. This will affect # Or set the config `do_not_backup_data` to 1 into the `settings.yml` of the app. This will affect
# all backups for this app until the setting is removed. # all backups for this app until the setting is removed.
# #
# Requires YunoHost version 2.4.0 or higher. # Requires YunoHost version 2.4.0 or higher.
# Requires YunoHost version 3.5.0 or higher for the argument --not_mandatory # Requires YunoHost version 3.5.0 or higher for the argument `--not_mandatory`
ynh_backup() { ynh_backup() {
# TODO find a way to avoid injection by file strange naming ! # TODO find a way to avoid injection by file strange naming !
@ -221,26 +223,25 @@ with open(sys.argv[1], 'r') as backup_file:
# Restore a file or a directory # Restore a file or a directory
# #
# Use the registered path in backup_list by ynh_backup to restore the file at
# the right place.
#
# usage: ynh_restore_file --origin_path=origin_path [--dest_path=dest_path] [--not_mandatory] # usage: ynh_restore_file --origin_path=origin_path [--dest_path=dest_path] [--not_mandatory]
# | arg: -o, --origin_path= - Path where was located the file or the directory before to be backuped or relative path to $YNH_CWD where it is located in the backup archive # | arg: -o, --origin_path= - Path where was located the file or the directory before to be backuped or relative path to $YNH_CWD where it is located in the backup archive
# | arg: -d, --dest_path= - Path where restore the file or the dir, if unspecified, the destination will be ORIGIN_PATH or if the ORIGIN_PATH doesn't exist in the archive, the destination will be searched into backup.csv # | arg: -d, --dest_path= - Path where restore the file or the dir. If unspecified, the destination will be `ORIGIN_PATH` or if the `ORIGIN_PATH` doesn't exist in the archive, the destination will be searched into `backup.csv`
# | arg: -m, --not_mandatory - Indicate that if the file is missing, the restore process can ignore it. # | arg: -m, --not_mandatory - Indicate that if the file is missing, the restore process can ignore it.
# #
# Use the registered path in backup_list by ynh_backup to restore the file at the right place.
#
# examples: # examples:
# ynh_restore_file "/etc/nginx/conf.d/$domain.d/$app.conf" # ynh_restore_file -o "/etc/nginx/conf.d/$domain.d/$app.conf"
# # You can also use relative paths: # # You can also use relative paths:
# ynh_restore_file "conf/nginx.conf" # ynh_restore_file -o "conf/nginx.conf"
# #
# If DEST_PATH already exists and is lighter than 500 Mo, a backup will be made in # If `DEST_PATH` already exists and is lighter than 500 Mo, a backup will be made in
# /home/yunohost.conf/backup/. Otherwise, the existing file is removed. # `/home/yunohost.conf/backup/`. Otherwise, the existing file is removed.
# #
# if apps/wordpress/etc/nginx/conf.d/$domain.d/$app.conf exists, restore it into # if `apps/$app/etc/nginx/conf.d/$domain.d/$app.conf` exists, restore it into
# /etc/nginx/conf.d/$domain.d/$app.conf # `/etc/nginx/conf.d/$domain.d/$app.conf`
# if no, search for a match in the csv (eg: conf/nginx.conf) and restore it into # if no, search for a match in the csv (eg: conf/nginx.conf) and restore it into
# /etc/nginx/conf.d/$domain.d/$app.conf # `/etc/nginx/conf.d/$domain.d/$app.conf`
# #
# Requires YunoHost version 2.6.4 or higher. # Requires YunoHost version 2.6.4 or higher.
# Requires YunoHost version 3.5.0 or higher for the argument --not_mandatory # Requires YunoHost version 3.5.0 or higher for the argument --not_mandatory
@ -346,13 +347,13 @@ ynh_store_file_checksum () {
# Verify the checksum and backup the file if it's different # Verify the checksum and backup the file if it's different
# #
# This helper is primarily meant to allow to easily backup personalised/manually
# modified config files.
#
# usage: ynh_backup_if_checksum_is_different --file=file # usage: ynh_backup_if_checksum_is_different --file=file
# | arg: -f, --file= - The file on which the checksum test will be perfomed. # | arg: -f, --file= - The file on which the checksum test will be perfomed.
# | ret: the name of a backup file, or nothing # | ret: the name of a backup file, or nothing
# #
# This helper is primarily meant to allow to easily backup personalised/manually
# modified config files.
#
# Requires YunoHost version 2.6.4 or higher. # Requires YunoHost version 2.6.4 or higher.
ynh_backup_if_checksum_is_different () { ynh_backup_if_checksum_is_different () {
# Declare an array to define the options of this helper. # Declare an array to define the options of this helper.
@ -410,12 +411,16 @@ ynh_backup_archive_exists () {
# Make a backup in case of failed upgrade # Make a backup in case of failed upgrade
# #
# usage: # usage: ynh_backup_before_upgrade
#
# Usage in a package script:
# ```
# ynh_backup_before_upgrade # ynh_backup_before_upgrade
# ynh_clean_setup () { # ynh_clean_setup () {
# ynh_restore_upgradebackup # ynh_restore_upgradebackup
# } # }
# ynh_abort_if_errors # ynh_abort_if_errors
# ```
# #
# Requires YunoHost version 2.7.2 or higher. # Requires YunoHost version 2.7.2 or higher.
ynh_backup_before_upgrade () { ynh_backup_before_upgrade () {
@ -459,12 +464,16 @@ ynh_backup_before_upgrade () {
# Restore a previous backup if the upgrade process failed # Restore a previous backup if the upgrade process failed
# #
# usage: # usage: ynh_restore_upgradebackup
#
# Usage in a package script:
# ```
# ynh_backup_before_upgrade # ynh_backup_before_upgrade
# ynh_clean_setup () { # ynh_clean_setup () {
# ynh_restore_upgradebackup # ynh_restore_upgradebackup
# } # }
# ynh_abort_if_errors # ynh_abort_if_errors
# ```
# #
# Requires YunoHost version 2.7.2 or higher. # Requires YunoHost version 2.7.2 or higher.
ynh_restore_upgradebackup () { ynh_restore_upgradebackup () {