From d69f031d8fffedbfe916f91f493c32ea5d627ef1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A9lix=20Pi=C3=A9dallu?= Date: Wed, 3 Mar 2021 10:58:34 +0100 Subject: [PATCH] helper doc fixes : backup --- data/helpers.d/backup | 79 ++++++++++++++++++++++++------------------- 1 file changed, 44 insertions(+), 35 deletions(-) diff --git a/data/helpers.d/backup b/data/helpers.d/backup index 33a6db4e2..17da0fb2e 100644 --- a/data/helpers.d/backup +++ b/data/helpers.d/backup @@ -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 # -# 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 # -# If DEST is ended by a slash it complete this path with the basename of SRC. -# -# Example in the context of a wordpress app +# 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 : +# ``` # ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" # # => 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" @@ -40,26 +40,28 @@ CAN_BIND=${CAN_BIND:-1} # ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "/conf/" # # => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/$app.conf" # +# ``` # -# How to use --is_big: -# --is_big is used to specify that this part of the backup can be quite huge. +# How to use `--is_big`: +# +# `--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. # 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. -# -# 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 -# 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 ! +# each of his backup. And so handle that part differently. # -# 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 -# only that backup command. -# 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. +# 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` +# 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 ! +# +# 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 +# only that backup command. +# 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. # # 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() { # TODO find a way to avoid injection by file strange naming ! @@ -81,7 +83,7 @@ ynh_backup() { # If backing up core only (used by ynh_backup_before_upgrade), # don't backup big data items - if [ $is_big -eq 1 ] && ( [ ${do_not_backup_data:-0} -eq 1 ] || [ $BACKUP_CORE_ONLY -eq 1 ] ) + if [ $is_big -eq 1 ] && ( [ ${do_not_backup_data:-0} -eq 1 ] || [ $BACKUP_CORE_ONLY -eq 1 ] ) then if [ $BACKUP_CORE_ONLY -eq 1 ] then @@ -221,26 +223,25 @@ with open(sys.argv[1], 'r') as backup_file: # 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] # | 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. # +# Use the registered path in backup_list by ynh_backup to restore the file at the right place. +# # 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: -# 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 -# /home/yunohost.conf/backup/. Otherwise, the existing file is removed. +# 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. # -# if apps/wordpress/etc/nginx/conf.d/$domain.d/$app.conf exists, restore it into -# /etc/nginx/conf.d/$domain.d/$app.conf +# if `apps/$app/etc/nginx/conf.d/$domain.d/$app.conf` exists, restore it into +# `/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 -# /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 3.5.0 or higher for the argument --not_mandatory @@ -345,14 +346,14 @@ ynh_store_file_checksum () { } # 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 # | arg: -f, --file= - The file on which the checksum test will be perfomed. # | 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. ynh_backup_if_checksum_is_different () { # 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 # -# usage: +# usage: ynh_backup_before_upgrade +# +# Usage in a package script: +# ``` # ynh_backup_before_upgrade # ynh_clean_setup () { # ynh_restore_upgradebackup # } # ynh_abort_if_errors +# ``` # # Requires YunoHost version 2.7.2 or higher. ynh_backup_before_upgrade () { @@ -459,12 +464,16 @@ ynh_backup_before_upgrade () { # Restore a previous backup if the upgrade process failed # -# usage: +# usage: ynh_restore_upgradebackup +# +# Usage in a package script: +# ``` # ynh_backup_before_upgrade # ynh_clean_setup () { # ynh_restore_upgradebackup # } # ynh_abort_if_errors +# ``` # # Requires YunoHost version 2.7.2 or higher. ynh_restore_upgradebackup () {