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

Merge pull request #1167 from Salamandar/fix_helper_doc

Browse source 
helper doc : Fix all doc (mostly)
This commit is contained in:
Alexandre Aubin 2021-03-17 15:41:26 +01:00 • committed by GitHub
commit f84b6535f3
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
19 changed files with 264 additions and 248 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
data/helpers.d/apt
View file

@ -47,10 +47,11 @@ ynh_wait_dpkg_free() {
# Check either a package is installed or not # Check either a package is installed or not
# #
# example: ynh_package_is_installed --package=yunohost && echo "ok" # example: ynh_package_is_installed --package=yunohost && echo "installed"
# #
# usage: ynh_package_is_installed --package=name # usage: ynh_package_is_installed --package=name
# | arg: -p, --package= - the package name to check # | arg: -p, --package= - the package name to check
# | ret: 0 if the package is installed, 1 else.
# #
# Requires YunoHost version 2.2.4 or higher. # Requires YunoHost version 2.2.4 or higher.
ynh_package_is_installed() { ynh_package_is_installed() {
@ -180,7 +181,7 @@ ynh_package_install_from_equivs () {
# Build and install the package # Build and install the package
local TMPDIR=$(mktemp --directory) local TMPDIR=$(mktemp --directory)
# Force the compatibility level at 10, levels below are deprecated # Force the compatibility level at 10, levels below are deprecated
echo 10 > /usr/share/equivs/template/debian/compat echo 10 > /usr/share/equivs/template/debian/compat
# Note that the cd executes into a sub shell # Note that the cd executes into a sub shell
@ -194,7 +195,7 @@ ynh_package_install_from_equivs () {
LC_ALL=C dpkg --force-depends --install "./${pkgname}_${pkgversion}_all.deb" 2>&1 | tee ./dpkg_log) LC_ALL=C dpkg --force-depends --install "./${pkgname}_${pkgversion}_all.deb" 2>&1 | tee ./dpkg_log)
ynh_package_install --fix-broken || \ ynh_package_install --fix-broken || \
{ # If the installation failed { # If the installation failed
# (the following is ran inside { } to not start a subshell otherwise ynh_die wouldnt exit the original process) # (the following is ran inside { } to not start a subshell otherwise ynh_die wouldnt exit the original process)
# Parse the list of problematic dependencies from dpkg's log ... # Parse the list of problematic dependencies from dpkg's log ...
# (relevant lines look like: "foo-ynh-deps depends on bar; however:") # (relevant lines look like: "foo-ynh-deps depends on bar; however:")
@ -216,7 +217,8 @@ ynh_package_install_from_equivs () {
# example : ynh_install_app_dependencies dep1 dep2 "dep3|dep4|dep5" # example : ynh_install_app_dependencies dep1 dep2 "dep3|dep4|dep5"
# #
# usage: ynh_install_app_dependencies dep [dep [...]] # usage: ynh_install_app_dependencies dep [dep [...]]
# | arg: dep - the package name to install in dependence. Writing "dep3|dep4|dep5" can be used to specify alternatives. For example : dep1 dep2 "dep3|dep4|dep5" will require to install dep1 and dep 2 and (dep3 or dep4 or dep5). # | arg: dep - the package name to install in dependence.
# | arg: "dep1|dep2|…" - You can specify alternatives. It will require to install (dep1 or dep2, etc).
# #
# Requires YunoHost version 2.6.4 or higher. # Requires YunoHost version 2.6.4 or higher.
ynh_install_app_dependencies () { ynh_install_app_dependencies () {
@ -250,7 +252,7 @@ ynh_install_app_dependencies () {
# Epic ugly hack to fix the goddamn dependency nightmare of sury # Epic ugly hack to fix the goddamn dependency nightmare of sury
# Sponsored by the "Djeezusse Fokin Kraiste Why Do Adminsys Has To Be So Fucking Complicated I Should Go Grow Potatoes Instead Of This Shit" collective # Sponsored by the "Djeezusse Fokin Kraiste Why Do Adminsys Has To Be So Fucking Complicated I Should Go Grow Potatoes Instead Of This Shit" collective
# https://github.com/YunoHost/issues/issues/1407 # https://github.com/YunoHost/issues/issues/1407
# #
# If we require to install php dependency # If we require to install php dependency
if echo $dependencies | grep --quiet 'php' if echo $dependencies | grep --quiet 'php'
then then

79
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.
# 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 # As this part of your backup may not be done, your restore script has to handle it.
# variable BACKUP_CORE_ONLY to 1 (BACKUP_CORE_ONLY=1) before the backup command. It will affect # In your restore script, use `--not_mandatory` with `ynh_restore_file`
# only that backup command. # As well in your remove script, you should not remove those data ! Or an user may end up with
# Or set the config do_not_backup_data to 1 into the settings.yml of the app. This will affect # a failed upgrade restoring an app without data anymore !
# all backups for this app until the setting is removed. #
# 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 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 !
@ -81,7 +83,7 @@ ynh_backup() {
# If backing up core only (used by ynh_backup_before_upgrade), # If backing up core only (used by ynh_backup_before_upgrade),
# don't backup big data items # 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 then
if [ $BACKUP_CORE_ONLY -eq 1 ] if [ $BACKUP_CORE_ONLY -eq 1 ]
then then
@ -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
@ -345,14 +346,14 @@ 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 () {

27
data/helpers.d/fail2ban
View file

@ -12,15 +12,14 @@
# #
# usage 2: ynh_add_fail2ban_config --use_template [--others_var="list of others variables to replace"] # usage 2: ynh_add_fail2ban_config --use_template [--others_var="list of others variables to replace"]
# | arg: -t, --use_template - Use this helper in template mode # | arg: -t, --use_template - Use this helper in template mode
# | arg: -v, --others_var= - List of others variables to replace separeted by a space # | arg: -v, --others_var= - List of others variables to replace separeted by a space for example : 'var_1 var_2 ...'
# | for example : 'var_1 var_2 ...'
# #
# This will use a template in ../conf/f2b_jail.conf and ../conf/f2b_filter.conf # This will use a template in `../conf/f2b_jail.conf` and `../conf/f2b_filter.conf`
# See the documentation of ynh_add_config for a description of the template # See the documentation of `ynh_add_config` for a description of the template
# format and how placeholders are replaced with actual variables. # format and how placeholders are replaced with actual variables.
# #
# Generally your template will look like that by example (for synapse): # Generally your template will look like that by example (for synapse):
# # ```
# f2b_jail.conf: # f2b_jail.conf:
# [__APP__] # [__APP__]
# enabled = true # enabled = true
@ -28,7 +27,8 @@
# filter = __APP__ # filter = __APP__
# logpath = /var/log/__APP__/logfile.log # logpath = /var/log/__APP__/logfile.log
# maxretry = 3 # maxretry = 3
# # ```
# ```
# f2b_filter.conf: # f2b_filter.conf:
# [INCLUDES] # [INCLUDES]
# before = common.conf # before = common.conf
@ -41,22 +41,25 @@
# failregex = ^%(__synapse_start_line)s INFO \- POST\-(\d+)\- <HOST> \- \d+ \- Received request\: POST /_matrix/client/r0/login\??<SKIPLINES>%(__synapse_start_line)s INFO \- POST\-\1\- Got login request with identifier: \{u'type': u'm.id.user', u'user'\: u'(.+?)'\}, medium\: None, address: None, user\: u'\5'<SKIPLINES>%(__synapse_start_line)s WARNING \- \- (Attempted to login as @\5\:.+ but they do not exist|Failed password login for user @\5\:.+)$ # failregex = ^%(__synapse_start_line)s INFO \- POST\-(\d+)\- <HOST> \- \d+ \- Received request\: POST /_matrix/client/r0/login\??<SKIPLINES>%(__synapse_start_line)s INFO \- POST\-\1\- Got login request with identifier: \{u'type': u'm.id.user', u'user'\: u'(.+?)'\}, medium\: None, address: None, user\: u'\5'<SKIPLINES>%(__synapse_start_line)s WARNING \- \- (Attempted to login as @\5\:.+ but they do not exist|Failed password login for user @\5\:.+)$
# #
# ignoreregex = # ignoreregex =
# ```
# #
# ----------------------------------------------------------------------------- # -----------------------------------------------------------------------------
# #
# Note about the "failregex" option: # Note about the "failregex" option:
# regex to match the password failure messages in the logfile. The
# host must be matched by a group named "host". The tag "<HOST>" can
# be used for standard IP/hostname matching and is only an alias for
# (?:::f{4,6}:)?(?P<host>[\w\-.^_]+)
# #
# You can find some more explainations about how to make a regex here : # regex to match the password failure messages in the logfile. The host must be
# https://www.fail2ban.org/wiki/index.php/MANUAL_0_8#Filters # matched by a group named "`host`". The tag "`<HOST>`" can be used for standard
# IP/hostname matching and is only an alias for `(?:::f{4,6}:)?(?P<host>[\w\-.^_]+)`
#
# You can find some more explainations about how to make a regex here :
# https://www.fail2ban.org/wiki/index.php/MANUAL_0_8#Filters
# #
# Note that the logfile need to exist before to call this helper !! # Note that the logfile need to exist before to call this helper !!
# #
# To validate your regex you can test with this command: # To validate your regex you can test with this command:
# ```
# fail2ban-regex /var/log/YOUR_LOG_FILE_PATH /etc/fail2ban/filter.d/YOUR_APP.conf # fail2ban-regex /var/log/YOUR_LOG_FILE_PATH /etc/fail2ban/filter.d/YOUR_APP.conf
# ```
# #
# Requires YunoHost version 3.5.0 or higher. # Requires YunoHost version 3.5.0 or higher.
ynh_add_fail2ban_config () { ynh_add_fail2ban_config () {

12
data/helpers.d/hardware
View file

@ -7,7 +7,7 @@
# | arg: -t, --total - Count total RAM+swap # | arg: -t, --total - Count total RAM+swap
# | arg: -s, --ignore_swap - Ignore swap, consider only real RAM # | arg: -s, --ignore_swap - Ignore swap, consider only real RAM
# | arg: -o, --only_swap - Ignore real RAM, consider only swap # | arg: -o, --only_swap - Ignore real RAM, consider only swap
# | ret: the amount of free ram # | ret: the amount of free ram, in MB (MegaBytes)
# #
# Requires YunoHost version 3.8.1 or higher. # Requires YunoHost version 3.8.1 or higher.
ynh_get_ram () { ynh_get_ram () {
@ -35,7 +35,7 @@ ynh_get_ram () {
local free_ram=$(vmstat --stats --unit M | grep "free memory" | awk '{print $1}') local free_ram=$(vmstat --stats --unit M | grep "free memory" | awk '{print $1}')
local free_swap=$(vmstat --stats --unit M | grep "free swap" | awk '{print $1}') local free_swap=$(vmstat --stats --unit M | grep "free swap" | awk '{print $1}')
local free_ram_swap=$(( free_ram + free_swap )) local free_ram_swap=$(( free_ram + free_swap ))
# Use the total amount of free ram # Use the total amount of free ram
local ram=$free_ram_swap local ram=$free_ram_swap
if [ $ignore_swap -eq 1 ] if [ $ignore_swap -eq 1 ]
@ -52,7 +52,7 @@ ynh_get_ram () {
local total_ram=$(vmstat --stats --unit M | grep "total memory" | awk '{print $1}') local total_ram=$(vmstat --stats --unit M | grep "total memory" | awk '{print $1}')
local total_swap=$(vmstat --stats --unit M | grep "total swap" | awk '{print $1}') local total_swap=$(vmstat --stats --unit M | grep "total swap" | awk '{print $1}')
local total_ram_swap=$(( total_ram + total_swap )) local total_ram_swap=$(( total_ram + total_swap ))
local ram=$total_ram_swap local ram=$total_ram_swap
if [ $ignore_swap -eq 1 ] if [ $ignore_swap -eq 1 ]
then then
@ -70,13 +70,13 @@ ynh_get_ram () {
# Return 0 or 1 depending if the system has a given amount of RAM+swap free or total # Return 0 or 1 depending if the system has a given amount of RAM+swap free or total
# #
# usage: ynh_require_ram --required=RAM required in Mb [--free|--total] [--ignore_swap|--only_swap] # usage: ynh_require_ram --required=RAM [--free|--total] [--ignore_swap|--only_swap]
# | arg: -r, --required= - The amount to require, in Mb # | arg: -r, --required= - The amount to require, in MB
# | arg: -f, --free - Count free RAM+swap # | arg: -f, --free - Count free RAM+swap
# | arg: -t, --total - Count total RAM+swap # | arg: -t, --total - Count total RAM+swap
# | arg: -s, --ignore_swap - Ignore swap, consider only real RAM # | arg: -s, --ignore_swap - Ignore swap, consider only real RAM
# | arg: -o, --only_swap - Ignore real RAM, consider only swap # | arg: -o, --only_swap - Ignore real RAM, consider only swap
# | exit: Return 1 if the ram is under the requirement, 0 otherwise. # | ret: 1 if the ram is under the requirement, 0 otherwise.
# #
# Requires YunoHost version 3.8.1 or higher. # Requires YunoHost version 3.8.1 or higher.
ynh_require_ram () { ynh_require_ram () {

18
data/helpers.d/logging
View file

@ -102,8 +102,7 @@ ynh_print_err () {
# Execute a command and print the result as an error # Execute a command and print the result as an error
# #
# usage: ynh_exec_err your_command # usage: ynh_exec_err "your_command [ | other_command ]"
# usage: ynh_exec_err "your_command | other_command"
# | arg: command - command to execute # | arg: command - command to execute
# #
# When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe. # When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.
@ -117,8 +116,7 @@ ynh_exec_err () {
# Execute a command and print the result as a warning # Execute a command and print the result as a warning
# #
# usage: ynh_exec_warn your_command # usage: ynh_exec_warn "your_command [ | other_command ]"
# usage: ynh_exec_warn "your_command | other_command"
# | arg: command - command to execute # | arg: command - command to execute
# #
# When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe. # When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.
@ -132,8 +130,7 @@ ynh_exec_warn () {
# Execute a command and force the result to be printed on stdout # Execute a command and force the result to be printed on stdout
# #
# usage: ynh_exec_warn_less your_command # usage: ynh_exec_warn_less "your_command [ | other_command ]"
# usage: ynh_exec_warn_less "your_command | other_command"
# | arg: command - command to execute # | arg: command - command to execute
# #
# When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe. # When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.
@ -147,8 +144,7 @@ ynh_exec_warn_less () {
# Execute a command and redirect stdout in /dev/null # Execute a command and redirect stdout in /dev/null
# #
# usage: ynh_exec_quiet your_command # usage: ynh_exec_quiet "your_command [ | other_command ]"
# usage: ynh_exec_quiet "your_command | other_command"
# | arg: command - command to execute # | arg: command - command to execute
# #
# When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe. # When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.
@ -162,8 +158,7 @@ ynh_exec_quiet () {
# Execute a command and redirect stdout and stderr in /dev/null # Execute a command and redirect stdout and stderr in /dev/null
# #
# usage: ynh_exec_fully_quiet your_command # usage: ynh_exec_fully_quiet "your_command [ | other_command ]"
# usage: ynh_exec_fully_quiet "your_command | other_command"
# | arg: command - command to execute # | arg: command - command to execute
# #
# When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe. # When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.
@ -363,8 +358,7 @@ ynh_debug () {
# Execute a command and print the result as debug # Execute a command and print the result as debug
# #
# usage: ynh_debug_exec your_command # usage: ynh_debug_exec "your_command [ | other_command ]"
# usage: ynh_debug_exec "your_command | other_command"
# | arg: command - command to execute # | arg: command - command to execute
# #
# When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe. # When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

10
data/helpers.d/logrotate
View file

@ -7,16 +7,14 @@
# | arg: -n, --nonappend - (optional) Replace the config file instead of appending this new config. # | arg: -n, --nonappend - (optional) Replace the config file instead of appending this new config.
# | arg: -u, --specific_user= - run logrotate as the specified user and group. If not specified logrotate is runned as root. # | arg: -u, --specific_user= - run logrotate as the specified user and group. If not specified logrotate is runned as root.
# #
# If no --logfile is provided, /var/log/${app} will be used as default. # If no `--logfile` is provided, `/var/log/$app` will be used as default.
# logfile can be just a directory, or a full path to a logfile : # `logfile` can point to a directory or a file.
# /parentdir/logdir
# /parentdir/logdir/logfile.log
# #
# It's possible to use this helper multiple times, each config will be added to # It's possible to use this helper multiple times, each config will be added to
# the same logrotate config file. Unless you use the option --non-append # the same logrotate config file. Unless you use the option `--non-append`
# #
# Requires YunoHost version 2.6.4 or higher. # Requires YunoHost version 2.6.4 or higher.
# Requires YunoHost version 3.2.0 or higher for the argument --specific_user # Requires YunoHost version 3.2.0 or higher for the argument `--specific_user`
ynh_use_logrotate () { ynh_use_logrotate () {
# Declare an array to define the options of this helper. # Declare an array to define the options of this helper.
local legacy_args=lnuya local legacy_args=lnuya

7
data/helpers.d/multimedia
View file

@ -47,12 +47,14 @@ ynh_multimedia_build_main_dir() {
} }
# Add a directory in yunohost.multimedia # Add a directory in yunohost.multimedia
# This "directory" will be a symbolic link to a existing directory.
# #
# usage: ynh_multimedia_addfolder "Source directory" "Destination directory" # usage: ynh_multimedia_addfolder --source_dir="source_dir" --dest_dir="dest_dir"
# #
# | arg: -s, --source_dir= - Source directory - The real directory which contains your medias. # | arg: -s, --source_dir= - Source directory - The real directory which contains your medias.
# | arg: -d, --dest_dir= - Destination directory - The name and the place of the symbolic link, relative to "/home/yunohost.multimedia" # | arg: -d, --dest_dir= - Destination directory - The name and the place of the symbolic link, relative to "/home/yunohost.multimedia"
#
# This "directory" will be a symbolic link to a existing directory.
#
ynh_multimedia_addfolder() { ynh_multimedia_addfolder() {
# Declare an array to define the options of this helper. # Declare an array to define the options of this helper.
@ -80,6 +82,7 @@ ynh_multimedia_addfolder() {
# usage: ynh_multimedia_addaccess user_name # usage: ynh_multimedia_addaccess user_name
# #
# | arg: -u, --user_name= - The name of the user which gain this access. # | arg: -u, --user_name= - The name of the user which gain this access.
#
ynh_multimedia_addaccess () { ynh_multimedia_addaccess () {
# Declare an array to define the options of this helper. # Declare an array to define the options of this helper.
local legacy_args=u local legacy_args=u

19
data/helpers.d/mysql
View file

@ -2,14 +2,15 @@
# Open a connection as a user # Open a connection as a user
# #
# example: ynh_mysql_connect_as --user="user" --password="pass" <<< "UPDATE ...;"
# example: ynh_mysql_connect_as --user="user" --password="pass" < /path/to/file.sql
#
# usage: ynh_mysql_connect_as --user=user --password=password [--database=database] # usage: ynh_mysql_connect_as --user=user --password=password [--database=database]
# | arg: -u, --user= - the user name to connect as # | arg: -u, --user= - the user name to connect as
# | arg: -p, --password= - the user password # | arg: -p, --password= - the user password
# | arg: -d, --database= - the database to connect to # | arg: -d, --database= - the database to connect to
# #
# examples:
# ynh_mysql_connect_as --user="user" --password="pass" <<< "UPDATE ...;"
# ynh_mysql_connect_as --user="user" --password="pass" < /path/to/file.sql
#
# Requires YunoHost version 2.2.4 or higher. # Requires YunoHost version 2.2.4 or higher.
ynh_mysql_connect_as() { ynh_mysql_connect_as() {
# Declare an array to define the options of this helper. # Declare an array to define the options of this helper.
@ -120,11 +121,11 @@ ynh_mysql_drop_db() {
# Dump a database # Dump a database
# #
# example: ynh_mysql_dump_db --database=roundcube > ./dump.sql
#
# usage: ynh_mysql_dump_db --database=database # usage: ynh_mysql_dump_db --database=database
# | arg: -d, --database= - the database name to dump # | arg: -d, --database= - the database name to dump
# | ret: the mysqldump output # | ret: The mysqldump output
#
# example: ynh_mysql_dump_db --database=roundcube > ./dump.sql
# #
# Requires YunoHost version 2.2.4 or higher. # Requires YunoHost version 2.2.4 or higher.
ynh_mysql_dump_db() { ynh_mysql_dump_db() {
@ -156,7 +157,7 @@ ynh_mysql_create_user() {
# #
# usage: ynh_mysql_user_exists --user=user # usage: ynh_mysql_user_exists --user=user
# | arg: -u, --user= - the user for which to check existence # | arg: -u, --user= - the user for which to check existence
# | exit: Return 1 if the user doesn't exist, 0 otherwise. # | ret: 0 if the user exists, 1 otherwise.
# #
# Requires YunoHost version 2.2.4 or higher. # Requires YunoHost version 2.2.4 or higher.
ynh_mysql_user_exists() ynh_mysql_user_exists()
@ -195,8 +196,8 @@ ynh_mysql_drop_user() {
# | arg: -n, --db_name= - Name of the database # | arg: -n, --db_name= - Name of the database
# | arg: -p, --db_pwd= - Password of the database. If not provided, a password will be generated # | arg: -p, --db_pwd= - Password of the database. If not provided, a password will be generated
# #
# After executing this helper, the password of the created database will be available in $db_pwd # After executing this helper, the password of the created database will be available in `$db_pwd`
# It will also be stored as "mysqlpwd" into the app settings. # It will also be stored as "`mysqlpwd`" into the app settings.
# #
# Requires YunoHost version 2.6.4 or higher. # Requires YunoHost version 2.6.4 or higher.
ynh_mysql_setup_db () { ynh_mysql_setup_db () {

20
data/helpers.d/network
View file

@ -2,12 +2,12 @@
# Find a free port and return it # Find a free port and return it
# #
# example: port=$(ynh_find_port --port=8080)
#
# usage: ynh_find_port --port=begin_port # usage: ynh_find_port --port=begin_port
# | arg: -p, --port= - port to start to search # | arg: -p, --port= - port to start to search
# | ret: the port number # | ret: the port number
# #
# example: port=$(ynh_find_port --port=8080)
#
# Requires YunoHost version 2.6.4 or higher. # Requires YunoHost version 2.6.4 or higher.
ynh_find_port () { ynh_find_port () {
# Declare an array to define the options of this helper. # Declare an array to define the options of this helper.
@ -27,11 +27,11 @@ ynh_find_port () {
# Test if a port is available # Test if a port is available
# #
# example: ynh_port_available --port=1234 || ynh_die --message="Port 1234 is needs to be available for this app"
#
# usage: ynh_find_port --port=XYZ # usage: ynh_find_port --port=XYZ
# | arg: -p, --port= - port to check # | arg: -p, --port= - port to check
# | exit: Return 1 if the port is already used by another process. # | ret: 0 if the port is available, 1 if it is already used by another process.
#
# example: ynh_port_available --port=1234 || ynh_die --message="Port 1234 is needs to be available for this app"
# #
# Requires YunoHost version 3.8.0 or higher. # Requires YunoHost version 3.8.0 or higher.
ynh_port_available () { ynh_port_available () {
@ -89,12 +89,12 @@ EOF
# Validate an IPv4 address # Validate an IPv4 address
# #
# example: ynh_validate_ip4 111.222.333.444
#
# usage: ynh_validate_ip4 --ip_address=ip_address # usage: ynh_validate_ip4 --ip_address=ip_address
# | arg: -i, --ip_address= - the ipv4 address to check # | arg: -i, --ip_address= - the ipv4 address to check
# | ret: 0 for valid ipv4 addresses, 1 otherwise # | ret: 0 for valid ipv4 addresses, 1 otherwise
# #
# example: ynh_validate_ip4 111.222.333.444
#
# Requires YunoHost version 2.2.4 or higher. # Requires YunoHost version 2.2.4 or higher.
ynh_validate_ip4() ynh_validate_ip4()
{ {
@ -111,12 +111,12 @@ ynh_validate_ip4()
# Validate an IPv6 address # Validate an IPv6 address
# #
# example: ynh_validate_ip6 2000:dead:beef::1
#
# usage: ynh_validate_ip6 --ip_address=ip_address # usage: ynh_validate_ip6 --ip_address=ip_address
# | arg: -i, --ip_address= - the ipv6 address to check # | arg: -i, --ip_address= - the ipv6 address to check
# | ret: 0 for valid ipv6 addresses, 1 otherwise # | ret: 0 for valid ipv6 addresses, 1 otherwise
# #
# example: ynh_validate_ip6 2000:dead:beef::1
#
# Requires YunoHost version 2.2.4 or higher. # Requires YunoHost version 2.2.4 or higher.
ynh_validate_ip6() ynh_validate_ip6()
{ {

8
data/helpers.d/nginx
View file

@ -4,13 +4,13 @@
# #
# usage: ynh_add_nginx_config # usage: ynh_add_nginx_config
# #
# This will use a template in ../conf/nginx.conf # This will use a template in `../conf/nginx.conf`
# See the documentation of ynh_add_config for a description of the template # See the documentation of `ynh_add_config` for a description of the template
# format and how placeholders are replaced with actual variables. # format and how placeholders are replaced with actual variables.
# #
# Additionally, ynh_add_nginx_config will replace: # Additionally, ynh_add_nginx_config will replace:
# - #sub_path_only by empty string if path_url is not '/' # - `#sub_path_only` by empty string if `path_url` is not `'/'`
# - #root_path_only by empty string if path_url *is* '/' # - `#root_path_only` by empty string if `path_url` *is* `'/'`
# #
# This allows to enable/disable specific behaviors dependenging on the install # This allows to enable/disable specific behaviors dependenging on the install
# location # location

43
data/helpers.d/nodejs
View file

@ -27,11 +27,14 @@ SOURCE_SUM=fa80a8685f0fb1b4187fc0a1228b44f0ea2f244e063fe8f443b8913ea595af89" > "
# Load the version of node for an app, and set variables. # Load the version of node for an app, and set variables.
# #
# ynh_use_nodejs has to be used in any app scripts before using node for the first time. # usage: ynh_use_nodejs
#
# `ynh_use_nodejs` has to be used in any app scripts before using node for the first time.
# This helper will provide alias and variables to use in your scripts. # This helper will provide alias and variables to use in your scripts.
# #
# To use npm or node, use the alias `ynh_npm` and `ynh_node` # To use npm or node, use the alias `ynh_npm` and `ynh_node`.
# Those alias will use the correct version installed for the app #
# Those alias will use the correct version installed for the app.
# For example: use `ynh_npm install` instead of `npm install` # For example: use `ynh_npm install` instead of `npm install`
# #
# With `sudo` or `ynh_exec_as`, use instead the fallback variables `$ynh_npm` and `$ynh_node` # With `sudo` or `ynh_exec_as`, use instead the fallback variables `$ynh_npm` and `$ynh_node`
@ -39,30 +42,32 @@ SOURCE_SUM=fa80a8685f0fb1b4187fc0a1228b44f0ea2f244e063fe8f443b8913ea595af89" > "
# Exemple: `ynh_exec_as $app $ynh_node_load_PATH $ynh_npm install` # Exemple: `ynh_exec_as $app $ynh_node_load_PATH $ynh_npm install`
# #
# $PATH contains the path of the requested version of node. # $PATH contains the path of the requested version of node.
# However, $PATH is duplicated into $node_PATH to outlast any manipulation of $PATH # However, $PATH is duplicated into $node_PATH to outlast any manipulation of `$PATH`
# You can use the variable `$ynh_node_load_PATH` to quickly load your node version # You can use the variable `$ynh_node_load_PATH` to quickly load your node version
# in $PATH for an usage into a separate script. # in $PATH for an usage into a separate script.
# Exemple: $ynh_node_load_PATH $final_path/script_that_use_npm.sh` # Exemple: $ynh_node_load_PATH $final_path/script_that_use_npm.sh`
# #
# #
# Finally, to start a nodejs service with the correct version, 2 solutions # Finally, to start a nodejs service with the correct version, 2 solutions
# Either the app is dependent of node or npm, but does not called it directly. # Either the app is dependent of node or npm, but does not called it directly.
# In such situation, you need to load PATH # In such situation, you need to load PATH :
# `Environment="__NODE_ENV_PATH__"` # ```
# `ExecStart=__FINALPATH__/my_app` # Environment="__NODE_ENV_PATH__"
# You will replace __NODE_ENV_PATH__ with $ynh_node_load_PATH # ExecStart=__FINALPATH__/my_app
# ```
# You will replace __NODE_ENV_PATH__ with $ynh_node_load_PATH.
# #
# Or node start the app directly, then you don't need to load the PATH variable # Or node start the app directly, then you don't need to load the PATH variable
# `ExecStart=__YNH_NODE__ my_app run` # ```
# You will replace __YNH_NODE__ with $ynh_node # ExecStart=__YNH_NODE__ my_app run
# ```
# You will replace __YNH_NODE__ with $ynh_node
# #
# #
# 2 other variables are also available # 2 other variables are also available
# - $nodejs_path: The absolute path to node binaries for the chosen version. # - $nodejs_path: The absolute path to node binaries for the chosen version.
# - $nodejs_version: Just the version number of node for this app. Stored as 'nodejs_version' in settings.yml. # - $nodejs_version: Just the version number of node for this app. Stored as 'nodejs_version' in settings.yml.
# #
# usage: ynh_use_nodejs
#
# Requires YunoHost version 2.7.12 or higher. # Requires YunoHost version 2.7.12 or higher.
ynh_use_nodejs () { ynh_use_nodejs () {
nodejs_version=$(ynh_app_setting_get --app=$app --key=nodejs_version) nodejs_version=$(ynh_app_setting_get --app=$app --key=nodejs_version)
@ -96,10 +101,10 @@ ynh_use_nodejs () {
# usage: ynh_install_nodejs --nodejs_version=nodejs_version # usage: ynh_install_nodejs --nodejs_version=nodejs_version
# | arg: -n, --nodejs_version= - Version of node to install. When possible, your should prefer to use major version number (e.g. 8 instead of 8.10.0). The crontab will then handle the update of minor versions when needed. # | arg: -n, --nodejs_version= - Version of node to install. When possible, your should prefer to use major version number (e.g. 8 instead of 8.10.0). The crontab will then handle the update of minor versions when needed.
# #
# n (Node version management) uses the PATH variable to store the path of the version of node it is going to use. # `n` (Node version management) uses the `PATH` variable to store the path of the version of node it is going to use.
# That's how it changes the version # That's how it changes the version
# #
# Refer to ynh_use_nodejs for more information about available commands and variables # Refer to `ynh_use_nodejs` for more information about available commands and variables
# #
# Requires YunoHost version 2.7.12 or higher. # Requires YunoHost version 2.7.12 or higher.
ynh_install_nodejs () { ynh_install_nodejs () {
@ -176,12 +181,12 @@ ynh_install_nodejs () {
# Remove the version of node used by the app. # Remove the version of node used by the app.
# #
# This helper will check if another app uses the same version of node,
# if not, this version of node will be removed.
# If no other app uses node, n will be also removed.
#
# usage: ynh_remove_nodejs # usage: ynh_remove_nodejs
# #
# This helper will check if another app uses the same version of node.
# - If not, this version of node will be removed.
# - If no other app uses node, n will be also removed.
#
# Requires YunoHost version 2.7.12 or higher. # Requires YunoHost version 2.7.12 or higher.
ynh_remove_nodejs () { ynh_remove_nodejs () {
nodejs_version=$(ynh_app_setting_get --app=$app --key=nodejs_version) nodejs_version=$(ynh_app_setting_get --app=$app --key=nodejs_version)

24
data/helpers.d/permission
View file

@ -2,15 +2,17 @@
# Create a new permission for the app # Create a new permission for the app
# #
# example 1: ynh_permission_create --permission=admin --url=/admin --additional_urls=domain.tld/admin /superadmin --allowed=alice bob \ # Example 1: `ynh_permission_create --permission=admin --url=/admin --additional_urls=domain.tld/admin /superadmin --allowed=alice bob \
# --label="My app admin" --show_tile=true # --label="My app admin" --show_tile=true`
# #
# This example will create a new permission permission with this following effect: # This example will create a new permission permission with this following effect:
# - A tile named "My app admin" in the SSO will be available for the users alice and bob. This tile will point to the relative url '/admin'. # - A tile named "My app admin" in the SSO will be available for the users alice and bob. This tile will point to the relative url '/admin'.
# - Only the user alice and bob will have the access to theses following url: /admin, domain.tld/admin, /superadmin # - Only the user alice and bob will have the access to theses following url: /admin, domain.tld/admin, /superadmin
# #
# #
# example 2: ynh_permission_create --permission=api --url=domain.tld/api --auth_header=false --allowed=visitors \ # Example 2:
#
# ynh_permission_create --permission=api --url=domain.tld/api --auth_header=false --allowed=visitors \
# --label="MyApp API" --protected=true # --label="MyApp API" --protected=true
# #
# This example will create a new protected permission. So the admin won't be able to add/remove the visitors group of this permission. # This example will create a new protected permission. So the admin won't be able to add/remove the visitors group of this permission.
@ -18,7 +20,7 @@
# With this permission all client will be allowed to access to the url 'domain.tld/api'. # With this permission all client will be allowed to access to the url 'domain.tld/api'.
# Note that in this case no tile will be show on the SSO. # Note that in this case no tile will be show on the SSO.
# Note that the auth_header parameter is to 'false'. So no authentication header will be passed to the application. # Note that the auth_header parameter is to 'false'. So no authentication header will be passed to the application.
# Generally the API is requested by an application and enabling the auth_header has no advantage and could bring some issues in some case. # Generally the API is requested by an application and enabling the auth_header has no advantage and could bring some issues in some case.
# So in this case it's better to disable this option for all API. # So in this case it's better to disable this option for all API.
# #
# #
@ -36,14 +38,14 @@
# #
# If provided, 'url' or 'additional_urls' is assumed to be relative to the app domain/path if they # If provided, 'url' or 'additional_urls' is assumed to be relative to the app domain/path if they
# start with '/'. For example: # start with '/'. For example:
# / -> domain.tld/app # / -> domain.tld/app
# /admin -> domain.tld/app/admin # /admin -> domain.tld/app/admin
# domain.tld/app/api -> domain.tld/app/api # domain.tld/app/api -> domain.tld/app/api
# #
# 'url' or 'additional_urls' can be treated as a PCRE (not lua) regex if it starts with "re:". # 'url' or 'additional_urls' can be treated as a PCRE (not lua) regex if it starts with "re:".
# For example: # For example:
# re:/api/[A-Z]*$ -> domain.tld/app/api/[A-Z]*$ # re:/api/[A-Z]*$ -> domain.tld/app/api/[A-Z]*$
# re:domain.tld/app/api/[A-Z]*$ -> domain.tld/app/api/[A-Z]*$ # re:domain.tld/app/api/[A-Z]*$ -> domain.tld/app/api/[A-Z]*$
# #
# Note that globally the parameter 'url' and 'additional_urls' are same. The only difference is: # Note that globally the parameter 'url' and 'additional_urls' are same. The only difference is:
# - 'url' is only one url, 'additional_urls' can be a list of urls. There are no limitation of 'additional_urls' # - 'url' is only one url, 'additional_urls' can be a list of urls. There are no limitation of 'additional_urls'
@ -56,7 +58,7 @@
# - "Remote-User": username # - "Remote-User": username
# - "Email": user email # - "Email": user email
# #
# Generally this feature is usefull to authenticate automatically the user in the application but in some case the application don't work with theses header and theses header need to be disabled to have the application to work correctly. # Generally this feature is usefull to authenticate automatically the user in the application but in some case the application don't work with theses header and theses header need to be disabled to have the application to work correctly.
# See https://github.com/YunoHost/issues/issues/1420 for more informations # See https://github.com/YunoHost/issues/issues/1420 for more informations
# #
# #
@ -186,7 +188,7 @@ ynh_permission_exists() {
# Redefine the url associated to a permission # Redefine the url associated to a permission
# #
# usage: ynh_permission_url --permission "permission" [--url="url"] [--add_url="new-url" [ "other-new-url" ]] [--remove_url="old-url" [ "other-old-url" ]] # usage: ynh_permission_url --permission "permission" [--url="url"] [--add_url="new-url" [ "other-new-url" ]] [--remove_url="old-url" [ "other-old-url" ]]
# [--auth_header=true|false] [--clear_urls] # [--auth_header=true|false] [--clear_urls]
# | arg: -p, --permission= - the name for the permission (by default a permission named "main" is removed automatically when the app is removed) # | arg: -p, --permission= - the name for the permission (by default a permission named "main" is removed automatically when the app is removed)
# | arg: -u, --url= - (optional) URL for which access will be allowed/forbidden. Note that if you want to remove url you can pass an empty sting as arguments (""). # | arg: -u, --url= - (optional) URL for which access will be allowed/forbidden. Note that if you want to remove url you can pass an empty sting as arguments ("").

2
data/helpers.d/php
View file

@ -569,6 +569,7 @@ YNH_COMPOSER_VERSION=${YNH_COMPOSER_VERSION:-$YNH_DEFAULT_COMPOSER_VERSION}
# | arg: -v, --phpversion - PHP version to use with composer # | arg: -v, --phpversion - PHP version to use with composer
# | arg: -w, --workdir - The directory from where the command will be executed. Default $final_path. # | arg: -w, --workdir - The directory from where the command will be executed. Default $final_path.
# | arg: -c, --commands - Commands to execute. # | arg: -c, --commands - Commands to execute.
#
ynh_composer_exec () { ynh_composer_exec () {
# Declare an array to define the options of this helper. # Declare an array to define the options of this helper.
local legacy_args=vwc local legacy_args=vwc
@ -593,6 +594,7 @@ ynh_composer_exec () {
# | arg: -w, --workdir - The directory from where the command will be executed. Default $final_path. # | arg: -w, --workdir - The directory from where the command will be executed. Default $final_path.
# | arg: -a, --install_args - Additional arguments provided to the composer install. Argument --no-dev already include # | arg: -a, --install_args - Additional arguments provided to the composer install. Argument --no-dev already include
# | arg: -c, --composerversion - Composer version to install # | arg: -c, --composerversion - Composer version to install
#
ynh_install_composer () { ynh_install_composer () {
# Declare an array to define the options of this helper. # Declare an array to define the options of this helper.
local legacy_args=vwac local legacy_args=vwac

19
data/helpers.d/postgresql
View file

@ -5,15 +5,15 @@ PSQL_VERSION=11
# Open a connection as a user # Open a connection as a user
# #
# examples:
# ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;"
# ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql
#
# usage: ynh_psql_connect_as --user=user --password=password [--database=database] # usage: ynh_psql_connect_as --user=user --password=password [--database=database]
# | arg: -u, --user= - the user name to connect as # | arg: -u, --user= - the user name to connect as
# | arg: -p, --password= - the user password # | arg: -p, --password= - the user password
# | arg: -d, --database= - the database to connect to # | arg: -d, --database= - the database to connect to
# #
# examples:
# ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;"
# ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql
#
# Requires YunoHost version 3.5.0 or higher. # Requires YunoHost version 3.5.0 or higher.
ynh_psql_connect_as() { ynh_psql_connect_as() {
# Declare an array to define the options of this helper. # Declare an array to define the options of this helper.
@ -127,12 +127,12 @@ ynh_psql_drop_db() {
# Dump a database # Dump a database
# #
# example: ynh_psql_dump_db 'roundcube' > ./dump.sql
#
# usage: ynh_psql_dump_db --database=database # usage: ynh_psql_dump_db --database=database
# | arg: -d, --database= - the database name to dump # | arg: -d, --database= - the database name to dump
# | ret: the psqldump output # | ret: the psqldump output
# #
# example: ynh_psql_dump_db 'roundcube' > ./dump.sql
#
# Requires YunoHost version 3.5.0 or higher. # Requires YunoHost version 3.5.0 or higher.
ynh_psql_dump_db() { ynh_psql_dump_db() {
# Declare an array to define the options of this helper. # Declare an array to define the options of this helper.
@ -243,7 +243,7 @@ ynh_psql_setup_db() {
local new_db_pwd=$(ynh_string_random) # Generate a random password local new_db_pwd=$(ynh_string_random) # Generate a random password
# If $db_pwd is not provided, use new_db_pwd instead for db_pwd # If $db_pwd is not provided, use new_db_pwd instead for db_pwd
db_pwd="${db_pwd:-$new_db_pwd}" db_pwd="${db_pwd:-$new_db_pwd}"
ynh_psql_create_user "$db_user" "$db_pwd" ynh_psql_create_user "$db_user" "$db_pwd"
elif [ -z $db_pwd ]; then elif [ -z $db_pwd ]; then
ynh_die --message="The user $db_user exists, please provide his password" ynh_die --message="The user $db_user exists, please provide his password"
@ -286,11 +286,12 @@ ynh_psql_remove_db() {
} }
# Create a master password and set up global settings # Create a master password and set up global settings
# It also make sure that postgresql is installed and running
# Please always call this script in install and restore scripts
# #
# usage: ynh_psql_test_if_first_run # usage: ynh_psql_test_if_first_run
# #
# It also make sure that postgresql is installed and running
# Please always call this script in install and restore scripts
#
# Requires YunoHost version 2.7.13 or higher. # Requires YunoHost version 2.7.13 or higher.
ynh_psql_test_if_first_run() { ynh_psql_test_if_first_run() {

10
data/helpers.d/setting
View file

@ -77,7 +77,7 @@ ynh_app_setting_delete() {
# [internal] # [internal]
# #
ynh_app_setting() ynh_app_setting()
{ {
set +o xtrace # set +x set +o xtrace # set +x
ACTION="$1" APP="$2" KEY="$3" VALUE="${4:-}" python3 - <<EOF ACTION="$1" APP="$2" KEY="$3" VALUE="${4:-}" python3 - <<EOF
import os, yaml, sys import os, yaml, sys
@ -108,12 +108,12 @@ EOF
# Check availability of a web path # Check availability of a web path
# #
# example: ynh_webpath_available --domain=some.domain.tld --path_url=/coffee
#
# usage: ynh_webpath_available --domain=domain --path_url=path # usage: ynh_webpath_available --domain=domain --path_url=path
# | arg: -d, --domain= - the domain/host of the url # | arg: -d, --domain= - the domain/host of the url
# | arg: -p, --path_url= - the web path to check the availability of # | arg: -p, --path_url= - the web path to check the availability of
# #
# example: ynh_webpath_available --domain=some.domain.tld --path_url=/coffee
#
# Requires YunoHost version 2.6.4 or higher. # Requires YunoHost version 2.6.4 or higher.
ynh_webpath_available () { ynh_webpath_available () {
# Declare an array to define the options of this helper. # Declare an array to define the options of this helper.
@ -129,13 +129,13 @@ ynh_webpath_available () {
# Register/book a web path for an app # Register/book a web path for an app
# #
# example: ynh_webpath_register --app=wordpress --domain=some.domain.tld --path_url=/coffee
#
# usage: ynh_webpath_register --app=app --domain=domain --path_url=path # usage: ynh_webpath_register --app=app --domain=domain --path_url=path
# | arg: -a, --app= - the app for which the domain should be registered # | arg: -a, --app= - the app for which the domain should be registered
# | arg: -d, --domain= - the domain/host of the web path # | arg: -d, --domain= - the domain/host of the web path
# | arg: -p, --path_url= - the web path to be registered # | arg: -p, --path_url= - the web path to be registered
# #
# example: ynh_webpath_register --app=wordpress --domain=some.domain.tld --path_url=/coffee
#
# Requires YunoHost version 2.6.4 or higher. # Requires YunoHost version 2.6.4 or higher.
ynh_webpath_register () { ynh_webpath_register () {
# Declare an array to define the options of this helper. # Declare an array to define the options of this helper.

16
data/helpers.d/string
View file

@ -2,12 +2,12 @@
# Generate a random string # Generate a random string
# #
# example: pwd=$(ynh_string_random --length=8)
#
# usage: ynh_string_random [--length=string_length] # usage: ynh_string_random [--length=string_length]
# | arg: -l, --length= - the string length to generate (default: 24) # | arg: -l, --length= - the string length to generate (default: 24)
# | ret: the generated string # | ret: the generated string
# #
# example: pwd=$(ynh_string_random --length=8)
#
# Requires YunoHost version 2.2.4 or higher. # Requires YunoHost version 2.2.4 or higher.
ynh_string_random() { ynh_string_random() {
# Declare an array to define the options of this helper. # Declare an array to define the options of this helper.
@ -30,9 +30,8 @@ ynh_string_random() {
# | arg: -r, --replace_string= - String that will replace matches # | arg: -r, --replace_string= - String that will replace matches
# | arg: -f, --target_file= - File in which the string will be replaced. # | arg: -f, --target_file= - File in which the string will be replaced.
# #
# As this helper is based on sed command, regular expressions and # As this helper is based on sed command, regular expressions and references to
# references to sub-expressions can be used # sub-expressions can be used (see sed manual page for more information)
# (see sed manual page for more information)
# #
# Requires YunoHost version 2.6.4 or higher. # Requires YunoHost version 2.6.4 or higher.
ynh_replace_string () { ynh_replace_string () {
@ -86,14 +85,15 @@ ynh_replace_special_string () {
} }
# Sanitize a string intended to be the name of a database # Sanitize a string intended to be the name of a database
# (More specifically : replace - and . by _)
#
# example: dbname=$(ynh_sanitize_dbid $app)
# #
# usage: ynh_sanitize_dbid --db_name=name # usage: ynh_sanitize_dbid --db_name=name
# | arg: -n, --db_name= - name to correct/sanitize # | arg: -n, --db_name= - name to correct/sanitize
# | ret: the corrected name # | ret: the corrected name
# #
# example: dbname=$(ynh_sanitize_dbid $app)
#
# Underscorify the string (replace - and . by _)
#
# Requires YunoHost version 2.2.4 or higher. # Requires YunoHost version 2.2.4 or higher.
ynh_sanitize_dbid () { ynh_sanitize_dbid () {
# Declare an array to define the options of this helper. # Declare an array to define the options of this helper.

14
data/helpers.d/systemd
View file

@ -3,11 +3,12 @@
# Create a dedicated systemd config # Create a dedicated systemd config
# #
# usage: ynh_add_systemd_config [--service=service] [--template=template] # usage: ynh_add_systemd_config [--service=service] [--template=template]
# | arg: -s, --service= - Service name (optionnal, $app by default) # | arg: -s, --service= - Service name (optionnal, `$app` by default)
# | arg: -t, --template= - Name of template file (optionnal, this is 'systemd' by default, meaning ./conf/systemd.service will be used as template) # | arg: -t, --template= - Name of template file (optionnal, this is 'systemd' by default, meaning `../conf/systemd.service` will be used as template)
# #
# This will use the template ../conf/<templatename>.service # This will use the template `../conf/<templatename>.service`.
# See the documentation of ynh_add_config for a description of the template #
# See the documentation of `ynh_add_config` for a description of the template
# format and how placeholders are replaced with actual variables. # format and how placeholders are replaced with actual variables.
# #
# Requires YunoHost version 2.7.11 or higher. # Requires YunoHost version 2.7.11 or higher.
@ -60,10 +61,10 @@ ynh_remove_systemd_config () {
# Start (or other actions) a service, print a log in case of failure and optionnaly wait until the service is completely started # Start (or other actions) a service, print a log in case of failure and optionnaly wait until the service is completely started
# #
# usage: ynh_systemd_action [--service_name=service_name] [--action=action] [ [--line_match="line to match"] [--log_path=log_path] [--timeout=300] [--length=20] ] # usage: ynh_systemd_action [--service_name=service_name] [--action=action] [ [--line_match="line to match"] [--log_path=log_path] [--timeout=300] [--length=20] ]
# | arg: -n, --service_name= - Name of the service to start. Default : $app # | arg: -n, --service_name= - Name of the service to start. Default : `$app`
# | arg: -a, --action= - Action to perform with systemctl. Default: start # | arg: -a, --action= - Action to perform with systemctl. Default: start
# | arg: -l, --line_match= - Line to match - The line to find in the log to attest the service have finished to boot. If not defined it don't wait until the service is completely started. # | arg: -l, --line_match= - Line to match - The line to find in the log to attest the service have finished to boot. If not defined it don't wait until the service is completely started.
# | arg: -p, --log_path= - Log file - Path to the log file. Default : /var/log/$app/$app.log # | arg: -p, --log_path= - Log file - Path to the log file. Default : `/var/log/$app/$app.log`
# | arg: -t, --timeout= - Timeout - The maximum time to wait before ending the watching. Default : 300 seconds. # | arg: -t, --timeout= - Timeout - The maximum time to wait before ending the watching. Default : 300 seconds.
# | arg: -e, --length= - Length of the error log : Default : 20 # | arg: -e, --length= - Length of the error log : Default : 20
# #
@ -181,4 +182,3 @@ ynh_clean_check_starting () {
ynh_secure_remove --file="$templog" 2>&1 ynh_secure_remove --file="$templog" 2>&1
fi fi
} }

37
data/helpers.d/user
View file

@ -2,11 +2,11 @@
# Check if a YunoHost user exists # Check if a YunoHost user exists
# #
# example: ynh_user_exists 'toto' || exit 1
#
# usage: ynh_user_exists --username=username # usage: ynh_user_exists --username=username
# | arg: -u, --username= - the username to check # | arg: -u, --username= - the username to check
# | exit: Return 1 if the user doesn't exist, 0 otherwise # | ret: 0 if the user exists, 1 otherwise.
#
# example: ynh_user_exists 'toto' || echo "User does not exist"
# #
# Requires YunoHost version 2.2.4 or higher. # Requires YunoHost version 2.2.4 or higher.
ynh_user_exists() { ynh_user_exists() {
@ -22,12 +22,12 @@ ynh_user_exists() {
# Retrieve a YunoHost user information # Retrieve a YunoHost user information
# #
# example: mail=$(ynh_user_get_info 'toto' 'mail')
#
# usage: ynh_user_get_info --username=username --key=key # usage: ynh_user_get_info --username=username --key=key
# | arg: -u, --username= - the username to retrieve info from # | arg: -u, --username= - the username to retrieve info from
# | arg: -k, --key= - the key to retrieve # | arg: -k, --key= - the key to retrieve
# | ret: string - the key's value # | ret: the value associate to that key
#
# example: mail=$(ynh_user_get_info 'toto' 'mail')
# #
# Requires YunoHost version 2.2.4 or higher. # Requires YunoHost version 2.2.4 or higher.
ynh_user_get_info() { ynh_user_get_info() {
@ -44,10 +44,10 @@ ynh_user_get_info() {
# Get the list of YunoHost users # Get the list of YunoHost users
# #
# example: for u in $(ynh_user_list); do ...
#
# usage: ynh_user_list # usage: ynh_user_list
# | ret: string - one username per line # | ret: one username per line as strings
#
# example: for u in $(ynh_user_list); do ... ; done
# #
# Requires YunoHost version 2.4.0 or higher. # Requires YunoHost version 2.4.0 or higher.
ynh_user_list() { ynh_user_list() {
@ -58,7 +58,7 @@ ynh_user_list() {
# #
# usage: ynh_system_user_exists --username=username # usage: ynh_system_user_exists --username=username
# | arg: -u, --username= - the username to check # | arg: -u, --username= - the username to check
# | exit: Return 1 if the user doesn't exist, 0 otherwise # | ret: 0 if the user exists, 1 otherwise.
# #
# Requires YunoHost version 2.2.4 or higher. # Requires YunoHost version 2.2.4 or higher.
ynh_system_user_exists() { ynh_system_user_exists() {
@ -76,7 +76,7 @@ ynh_system_user_exists() {
# #
# usage: ynh_system_group_exists --group=group # usage: ynh_system_group_exists --group=group
# | arg: -g, --group= - the group to check # | arg: -g, --group= - the group to check
# | exit: Return 1 if the group doesn't exist, 0 otherwise # | ret: 0 if the group exists, 1 otherwise.
# #
# Requires YunoHost version 3.5.0.2 or higher. # Requires YunoHost version 3.5.0.2 or higher.
ynh_system_group_exists() { ynh_system_group_exists() {
@ -92,17 +92,20 @@ ynh_system_group_exists() {
# Create a system user # Create a system user
# #
# examples:
# # Create a nextcloud user with no home directory and /usr/sbin/nologin login shell (hence no login capability)
# ynh_system_user_create --username=nextcloud
# # Create a discourse user using /var/www/discourse as home directory and the default login shell
# ynh_system_user_create --username=discourse --home_dir=/var/www/discourse --use_shell
#
# usage: ynh_system_user_create --username=user_name [--home_dir=home_dir] [--use_shell] # usage: ynh_system_user_create --username=user_name [--home_dir=home_dir] [--use_shell]
# | arg: -u, --username= - Name of the system user that will be create # | arg: -u, --username= - Name of the system user that will be create
# | arg: -h, --home_dir= - Path of the home dir for the user. Usually the final path of the app. If this argument is omitted, the user will be created without home # | arg: -h, --home_dir= - Path of the home dir for the user. Usually the final path of the app. If this argument is omitted, the user will be created without home
# | arg: -s, --use_shell - Create a user using the default login shell if present. If this argument is omitted, the user will be created with /usr/sbin/nologin shell # | arg: -s, --use_shell - Create a user using the default login shell if present. If this argument is omitted, the user will be created with /usr/sbin/nologin shell
# #
# Create a nextcloud user with no home directory and /usr/sbin/nologin login shell (hence no login capability) :
# ```
# ynh_system_user_create --username=nextcloud
# ```
# Create a discourse user using /var/www/discourse as home directory and the default login shell :
# ```
# ynh_system_user_create --username=discourse --home_dir=/var/www/discourse --use_shell
# ```
#
# Requires YunoHost version 2.6.4 or higher. # Requires YunoHost version 2.6.4 or higher.
ynh_system_user_create () { ynh_system_user_create () {
# Declare an array to define the options of this helper. # Declare an array to define the options of this helper.

135
data/helpers.d/utils
View file

@ -48,9 +48,8 @@ ynh_exit_properly () {
# usage: ynh_abort_if_errors # usage: ynh_abort_if_errors
# #
# This configure the rest of the script execution such that, if an error occurs # This configure the rest of the script execution such that, if an error occurs
# or if an empty variable is used, the execution of the script stops # or if an empty variable is used, the execution of the script stops immediately
# immediately and a call to `ynh_clean_setup` is triggered if it has been # and a call to `ynh_clean_setup` is triggered if it has been defined by your script.
# defined by your script.
# #
# Requires YunoHost version 2.6.4 or higher. # Requires YunoHost version 2.6.4 or higher.
ynh_abort_if_errors () { ynh_abort_if_errors () {
@ -63,45 +62,37 @@ ynh_abort_if_errors () {
# #
# usage: ynh_setup_source --dest_dir=dest_dir [--source_id=source_id] # usage: ynh_setup_source --dest_dir=dest_dir [--source_id=source_id]
# | arg: -d, --dest_dir= - Directory where to setup sources # | arg: -d, --dest_dir= - Directory where to setup sources
# | arg: -s, --source_id= - Name of the app, if the package contains more than one app # | arg: -s, --source_id= - Name of the source, defaults to `app`
# #
# The file conf/app.src need to contains: # This helper will read `conf/${source_id}.src`, download and install the sources.
# #
# The src file need to contains:
# ```
# SOURCE_URL=Address to download the app archive # SOURCE_URL=Address to download the app archive
# SOURCE_SUM=Control sum # SOURCE_SUM=Control sum
# # (Optional) Program to check the integrity (sha256sum, md5sum...) # # (Optional) Program to check the integrity (sha256sum, md5sum...). Default: sha256
# # default: sha256
# SOURCE_SUM_PRG=sha256 # SOURCE_SUM_PRG=sha256
# # (Optional) Archive format # # (Optional) Archive format. Default: tar.gz
# # default: tar.gz
# SOURCE_FORMAT=tar.gz # SOURCE_FORMAT=tar.gz
# # (Optional) Put false if sources are directly in the archive root # # (Optional) Put false if sources are directly in the archive root. Default: true
# # default: true # # Instead of true, SOURCE_IN_SUBDIR could be the number of sub directories to remove.
# # Instead of true, SOURCE_IN_SUBDIR could be the number of sub directories
# # to remove.
# SOURCE_IN_SUBDIR=false # SOURCE_IN_SUBDIR=false
# # (Optionnal) Name of the local archive (offline setup support) # # (Optionnal) Name of the local archive (offline setup support). Default: ${src_id}.${src_format}
# # default: ${src_id}.${src_format}
# SOURCE_FILENAME=example.tar.gz # SOURCE_FILENAME=example.tar.gz
# # (Optional) If it set as false don't extract the source. # # (Optional) If it set as false don't extract the source. Default: true
# # (Useful to get a debian package or a python wheel.) # # (Useful to get a debian package or a python wheel.)
# # default: true
# SOURCE_EXTRACT=(true|false) # SOURCE_EXTRACT=(true|false)
# ```
# #
# Details: # The helper will:
# This helper downloads sources from SOURCE_URL if there is no local source # - Check if there is a local source archive in `/opt/yunohost-apps-src/$APP_ID/$SOURCE_FILENAME`
# archive in /opt/yunohost-apps-src/APP_ID/SOURCE_FILENAME # - Download `$SOURCE_URL` if there is no local archive
# # - Check the integrity with `$SOURCE_SUM_PRG -c --status`
# Next, it checks the integrity with "SOURCE_SUM_PRG -c --status" command. # - Uncompress the archive to `$dest_dir`.
# # - If `$SOURCE_IN_SUBDIR` is true, the first level directory of the archive will be removed.
# If it's ok, the source archive will be uncompressed in $dest_dir. If the # - If `$SOURCE_IN_SUBDIR` is a numeric value, the N first level directories will be removed.
# SOURCE_IN_SUBDIR is true, the first level directory of the archive will be # - Patches named `sources/patches/${src_id}-*.patch` will be applied to `$dest_dir`
# removed. # - Extra files in `sources/extra_files/$src_id` will be copied to dest_dir
# If SOURCE_IN_SUBDIR is a numeric value, 2 for example, the 2 first level
# directories will be removed
#
# Finally, patches named sources/patches/${src_id}-*.patch and extra files in
# sources/extra_files/$src_id will be applied to dest_dir
# #
# Requires YunoHost version 2.6.4 or higher. # Requires YunoHost version 2.6.4 or higher.
ynh_setup_source () { ynh_setup_source () {
@ -214,17 +205,17 @@ ynh_setup_source () {
# Curl abstraction to help with POST requests to local pages (such as installation forms) # Curl abstraction to help with POST requests to local pages (such as installation forms)
# #
# example: ynh_local_curl "/install.php?installButton" "foo=$var1" "bar=$var2"
#
# usage: ynh_local_curl "page_uri" "key1=value1" "key2=value2" ... # usage: ynh_local_curl "page_uri" "key1=value1" "key2=value2" ...
# | arg: page_uri - Path (relative to $path_url) of the page where POST data will be sent # | arg: page_uri - Path (relative to `$path_url`) of the page where POST data will be sent
# | arg: key1=value1 - (Optionnal) POST key and corresponding value # | arg: key1=value1 - (Optionnal) POST key and corresponding value
# | arg: key2=value2 - (Optionnal) Another POST key and corresponding value # | arg: key2=value2 - (Optionnal) Another POST key and corresponding value
# | arg: ... - (Optionnal) More POST keys and values # | arg: ... - (Optionnal) More POST keys and values
# #
# example: ynh_local_curl "/install.php?installButton" "foo=$var1" "bar=$var2"
#
# For multiple calls, cookies are persisted between each call for the same app # For multiple calls, cookies are persisted between each call for the same app
# #
# $domain and $path_url should be defined externally (and correspond to the domain.tld and the /path (of the app?)) # `$domain` and `$path_url` should be defined externally (and correspond to the domain.tld and the /path (of the app?))
# #
# Requires YunoHost version 2.6.4 or higher. # Requires YunoHost version 2.6.4 or higher.
ynh_local_curl () { ynh_local_curl () {
@ -253,7 +244,7 @@ ynh_local_curl () {
# Wait untils nginx has fully reloaded (avoid curl fail with http2) # Wait untils nginx has fully reloaded (avoid curl fail with http2)
sleep 2 sleep 2
local cookiefile=/tmp/ynh-$app-cookie.txt local cookiefile=/tmp/ynh-$app-cookie.txt
touch $cookiefile touch $cookiefile
chown root $cookiefile chown root $cookiefile
@ -265,20 +256,22 @@ ynh_local_curl () {
# Create a dedicated config file from a template # Create a dedicated config file from a template
# #
# usage: ynh_add_config --template="template" --destination="destination"
# | arg: -t, --template= - Template config file to use
# | arg: -d, --destination= - Destination of the config file
#
# examples: # examples:
# ynh_add_config --template=".env" --destination="$final_path/.env" # ynh_add_config --template=".env" --destination="$final_path/.env"
# ynh_add_config --template="../conf/.env" --destination="$final_path/.env" # ynh_add_config --template="../conf/.env" --destination="$final_path/.env"
# ynh_add_config --template="/etc/nginx/sites-available/default" --destination="etc/nginx/sites-available/mydomain.conf" # ynh_add_config --template="/etc/nginx/sites-available/default" --destination="etc/nginx/sites-available/mydomain.conf"
# #
# usage: ynh_add_config --template="template" --destination="destination"
# | arg: -t, --template= - Template config file to use
# | arg: -d, --destination= - Destination of the config file
#
# The template can be by default the name of a file in the conf directory # The template can be by default the name of a file in the conf directory
# of a YunoHost Package, a relative path or an absolute path # of a YunoHost Package, a relative path or an absolute path.
# The helper will use the template $template to generate a config file #
# $destination by replacing the following keywords with global variables # The helper will use the template `template` to generate a config file
# `destination` by replacing the following keywords with global variables
# that should be defined before calling this helper : # that should be defined before calling this helper :
# ```
# __PATH__ by $path_url # __PATH__ by $path_url
# __NAME__ by $app # __NAME__ by $app
# __NAMETOCHANGE__ by $app # __NAMETOCHANGE__ by $app
@ -286,15 +279,18 @@ ynh_local_curl () {
# __FINALPATH__ by $final_path # __FINALPATH__ by $final_path
# __PHPVERSION__ by $YNH_PHP_VERSION # __PHPVERSION__ by $YNH_PHP_VERSION
# __YNH_NODE_LOAD_PATH__ by $ynh_node_load_PATH # __YNH_NODE_LOAD_PATH__ by $ynh_node_load_PATH
# # ```
# And any dynamic variables that should be defined before calling this helper like: # And any dynamic variables that should be defined before calling this helper like:
# ```
# __DOMAIN__ by $domain # __DOMAIN__ by $domain
# __APP__ by $app # __APP__ by $app
# __VAR_1__ by $var_1 # __VAR_1__ by $var_1
# __VAR_2__ by $var_2 # __VAR_2__ by $var_2
# ```
# #
# The helper will verify the checksum and backup the destination file # The helper will verify the checksum and backup the destination file
# if it's different before applying the new template. # if it's different before applying the new template.
#
# And it will calculate and store the destination file checksum # And it will calculate and store the destination file checksum
# into the app settings when configuration is done. # into the app settings when configuration is done.
# #
@ -559,16 +555,17 @@ ynh_read_manifest () {
jq ".$manifest_key" "$manifest" --raw-output jq ".$manifest_key" "$manifest" --raw-output
} }
# Read the upstream version from the manifest, or from the env variable $YNH_APP_MANIFEST_VERSION if not given # Read the upstream version from the manifest or `$YNH_APP_MANIFEST_VERSION`
# #
# usage: ynh_app_upstream_version [--manifest="manifest.json"] # usage: ynh_app_upstream_version [--manifest="manifest.json"]
# | arg: -m, --manifest= - Path of the manifest to read # | arg: -m, --manifest= - Path of the manifest to read
# | ret: the version number of the upstream app # | ret: the version number of the upstream app
# #
# The version number in the manifest is defined by <upstreamversion>~ynh<packageversion> # If the `manifest` is not specified, the envvar `$YNH_APP_MANIFEST_VERSION` will be used.
# For example : 4.3-2~ynh3 #
# This include the number before ~ynh # The version number in the manifest is defined by `<upstreamversion>~ynh<packageversion>`.
# In the last example it return 4.3-2 #
# For example, if the manifest contains `4.3-2~ynh3` the function will return `4.3-2`
# #
# Requires YunoHost version 3.5.0 or higher. # Requires YunoHost version 3.5.0 or higher.
ynh_app_upstream_version () { ynh_app_upstream_version () {
@ -596,10 +593,9 @@ ynh_app_upstream_version () {
# | arg: -m, --manifest= - Path of the manifest to read # | arg: -m, --manifest= - Path of the manifest to read
# | ret: the version number of the package # | ret: the version number of the package
# #
# The version number in the manifest is defined by <upstreamversion>~ynh<packageversion> # The version number in the manifest is defined by `<upstreamversion>~ynh<packageversion>`.
# For example : 4.3-2~ynh3 #
# This include the number after ~ynh # For example, if the manifest contains `4.3-2~ynh3` the function will return `3`
# In the last example it return 3
# #
# Requires YunoHost version 3.5.0 or higher. # Requires YunoHost version 3.5.0 or higher.
ynh_app_package_version () { ynh_app_package_version () {
@ -616,18 +612,16 @@ ynh_app_package_version () {
# Checks the app version to upgrade with the existing app version and returns: # Checks the app version to upgrade with the existing app version and returns:
# #
# - UPGRADE_PACKAGE if only the YunoHost package has changed # usage: ynh_check_app_version_changed
# - UPGRADE_APP otherwise # | ret: `UPGRADE_APP` if the upstream version changed, `UPGRADE_PACKAGE` otherwise.
# #
# This helper should be used to avoid an upgrade of an app, or the upstream part # This helper should be used to avoid an upgrade of an app, or the upstream part
# of it, when it's not needed # of it, when it's not needed
# #
# To force an upgrade, even if the package is up to date, # You can force an upgrade, even if the package is up to date, with the `--force` (or `-F`) argument :
# you have to use the parameter --force (or -F). # ```
# example: sudo yunohost app upgrade MyApp --force # sudo yunohost app upgrade <appname> --force
# # ```
# usage: ynh_check_app_version_changed
#
# Requires YunoHost version 3.5.0 or higher. # Requires YunoHost version 3.5.0 or higher.
ynh_check_app_version_changed () { ynh_check_app_version_changed () {
local return_value=${YNH_APP_UPGRADE_TYPE} local return_value=${YNH_APP_UPGRADE_TYPE}
@ -641,24 +635,23 @@ ynh_check_app_version_changed () {
} }
# Compare the current package version against another version given as an argument. # Compare the current package version against another version given as an argument.
# This is really useful when we need to do some actions only for some old package versions. #
# usage: ynh_compare_current_package_version --comparison (lt|le|eq|ne|ge|gt) --version <X~ynhY>
# | arg: --comparison - Comparison type. Could be : `lt` (lower than), `le` (lower or equal), `eq` (equal), `ne` (not equal), `ge` (greater or equal), `gt` (greater than)
# | arg: --version - The version to compare. Need to be a version in the yunohost package version type (like `2.3.1~ynh4`)
# | ret: 0 if the evaluation is true, 1 if false.
# #
# example: ynh_compare_current_package_version --comparison lt --version 2.3.2~ynh1 # example: ynh_compare_current_package_version --comparison lt --version 2.3.2~ynh1
# This example will check if the installed version is lower than (lt) the version 2.3.2~ynh1
# #
# Generally you might probably use it as follow in the upgrade script # This helper is usually used when we need to do some actions only for some old package versions.
# #
# Generally you might probably use it as follow in the upgrade script :
# ```
# if ynh_compare_current_package_version --comparison lt --version 2.3.2~ynh1 # if ynh_compare_current_package_version --comparison lt --version 2.3.2~ynh1
# then # then
# # Do something that is needed for the package version older than 2.3.2~ynh1 # # Do something that is needed for the package version older than 2.3.2~ynh1
# fi # fi
# # ```
# usage: ynh_compare_current_package_version --comparison lt|le|eq|ne|ge|gt
# | arg: --comparison - Comparison type. Could be : lt (lower than), le (lower or equal),
# | eq (equal), ne (not equal), ge (greater or equal), gt (greater than)
# | arg: --version - The version to compare. Need to be a version in the yunohost package version type (like 2.3.1~ynh4)
#
# Return 0 if the evaluation is true. 1 if false.
# #
# Requires YunoHost version 3.8.0 or higher. # Requires YunoHost version 3.8.0 or higher.
ynh_compare_current_package_version() { ynh_compare_current_package_version() {