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

6
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() {
@ -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 () {

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 () {

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 () {

8
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 () {
@ -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)

18
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.
@ -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'

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

17
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.
@ -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() {

8
data/helpers.d/setting
View file

@ -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.

133
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 () {
@ -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() {