Doc auto-generated by this script on 05/21/2020 (Yunohost version 3.8.4.3)
Usage: ynh_package_is_installed --package=name
Arguments:
-p, --package= : the package name to check
Example: ynh_package_is_installed --package=yunohost && echo "ok"
Details:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_package_version --package=name
Arguments:
-p, --package= : the package name to get versionReturns: the version or an empty string
Example: version=$(ynh_package_version --package=yunohost)
Details:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_package_update
Details:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_package_install name [name [...]]
Arguments:
name : the package name to installDetails:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_package_remove name [name [...]]
Arguments:
name : the package name to removeDetails:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_package_autoremove name [name [...]]
Arguments:
name : the package name to removeDetails:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_package_autopurge name [name [...]]
Arguments:
name : the package name to autoremove and purgeDetails:
Requires YunoHost version 2.7.2 or higher.
Usage: ynh_install_app_dependencies dep [dep [...]]
Arguments:
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).Details:
This helper can/should only be called once per appexample : ynh_install_app_dependencies dep1 dep2 "dep3|dep4|dep5"Requires YunoHost version 2.6.4 or higher.
Usage: ynh_add_app_dependencies --package=phpversion [--replace]
Arguments:
-p, --package= : Packages to add as dependencies for the app.-r, --replace : Replace dependencies instead of adding to existing ones.Details:
Requires YunoHost version 3.8.1 or higher.
Usage: ynh_remove_app_dependencies
Details:
Dependencies will removed only if no other package need them.Requires YunoHost version 2.6.4 or higher.
Usage: ynh_install_extra_app_dependencies --repo="repo" --package="dep1 dep2" [--key=key_url] [--name=name]
Arguments:
-r, --repo= : Complete url of the extra repository.-p, --package= : The packages to install from this extra repository-k, --key= : url to get the public key.-n, --name= : Name for the files for this repo, $app as default value.Details:
Requires YunoHost version 3.8.1 or higher.
Usage: ynh_backup --src_path=src_path [--dest_path=dest_path] [--is_big] [--not_mandatory]
Arguments:
-s, --src_path= : file or directory to bind or symlink or copy. it shouldn't be in the backup dir.-d, --dest_path= : destination file or directory inside the backup dir-b, --is_big : Indicate data are big (mail, video, image ...)-m, --not_mandatory : Indicate that if the file is missing, the backup can ignore it.arg : Deprecated argDetails:
This helper can be used both in a system backup hook, and in an app backup scriptDetails: ynh_backup writes SRC and the relative DEST into a CSV file. And itcreates the parent destination directoryIf DEST is ended by a slash it complete this path with the basename of SRC.Example in the context of a wordpress appynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf"# => This line will be added into CSV file# "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/etc/nginx/conf.d/$domain.d/$app.conf"ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf/nginx.conf"# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/nginx.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"ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf"# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf"#Deprecated usages (maintained for retro-compatibility)ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "${backup_dir}/conf/nginx.conf"# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/nginx.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"Requires YunoHost version 2.4.0 or higher.Requires YunoHost version 3.5.0 or higher for the argument --not_mandatory
Usage: ynh_restore_file --origin_path=origin_path [--dest_path=dest_path] [--not_mandatory]
Arguments:
-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-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-m, --not_mandatory : Indicate that if the file is missing, the restore process can ignore it.Examples:
ynh_restore_file "/etc/nginx/conf.d/$domain.d/$app.conf"
ynh_restore_file "conf/nginx.conf"
Details:
Use the registered path in backup_list by ynh_backup to restore the file atthe right place.If DEST_PATH already exists and is lighter than 500 Mo, a backup will be made in/home/yunohost.conf/backup/. Otherwise, the existing file is removed.if apps/wordpress/etc/nginx/conf.d/$domain.d/$app.conf exists, restore it into/etc/nginx/conf.d/$domain.d/$app.confif no, search for a match in the csv (eg: conf/nginx.conf) and restore it into/etc/nginx/conf.d/$domain.d/$app.confRequires YunoHost version 2.6.4 or higher.Requires YunoHost version 3.5.0 or higher for the argument --not_mandatory
Usage: ynh_store_file_checksum --file=file
Arguments:
-f, --file= : The file on which the checksum will performed, then stored.Details:
$app should be defined when calling this helperRequires YunoHost version 2.6.4 or higher.
Usage: ynh_backup_if_checksum_is_different --file=file
Arguments:
-f, --file= : The file on which the checksum test will be perfomed.Returns: the name of a backup file, or nothing
Details:
This helper is primarily meant to allow to easily backup personalised/manuallymodified config files.Requires YunoHost version 2.6.4 or higher.
Usage: ynh_delete_file_checksum --file=file
Arguments:
-f, --file= : The file for which the checksum will be deletedDetails:
$app should be defined when calling this helperRequires YunoHost version 3.3.1 or higher.
Usage: ynh_backup_before_upgrade
ynh_clean_setup () {
ynh_restore_upgradebackup
}
ynh_abort_if_errors
Details:
Requires YunoHost version 2.7.2 or higher.
Usage: ynh_backup_before_upgrade
ynh_clean_setup () {
ynh_restore_upgradebackup
}
ynh_abort_if_errors
Details:
Requires YunoHost version 2.7.2 or higher.
Usage: 1: ynh_add_fail2ban_config --logpath=log_file --failregex=filter [--max_retry=max_retry] [--ports=ports]
2: ynh_add_fail2ban_config --use_template [--others_var="list of others variables to replace"]
| for example : 'var_1 var_2 ...'
Arguments:
-l, --logpath= : Log file to be checked by fail2ban-r, --failregex= : Failregex to be looked for by fail2ban-m, --max_retry= : Maximum number of retries allowed before banning IP address - default: 3-p, --ports= : Ports blocked for a banned IP address - default: http,https-t, --use_template : Use this helper in template mode-v, --others_var= : List of others variables to replace separeted by a spaceDetails:
-----------------------------------------------------------------------------This will use a template in ../conf/f2b_jail.conf and ../conf/f2b_filter.conf __APP__ by $appYou can dynamically replace others variables by example : __VAR_1__ by $var_1 __VAR_2__ by $var_2Generally your template will look like that by example (for synapse):f2b_jail.conf: [__APP__] enabled = true port = http,https filter = __APP__ logpath = /var/log/__APP__/logfile.log maxretry = 3f2b_filter.conf: [INCLUDES] before = common.conf [Definition]# Part of regex definition (just used to make more easy to make the global regex) __synapse_start_line = .? \- synapse\..+ \-# Regex definition. failregex = ^%(__synapse_start_line)s INFO \- POST\-(\d+)\-
Usage: ynh_remove_fail2ban_config
Details:
Requires YunoHost version 3.5.0 or higher.
Usage: ynh_get_ram [--free|--total] [--ignore_swap|--only_swap]
Arguments:
-f, --free : Count free RAM+swap-t, --total : Count total RAM+swap-s, --ignore_swap : Ignore swap, consider only real RAM-o, --only_swap : Ignore real RAM, consider only swapReturns: the amount of free ram
Details:
Requires YunoHost version 3.8.1 or higher.
Usage: ynh_require_ram --required=RAM required in Mb [--free|--total] [--ignore_swap|--only_swap]
| exit: Return 1 if the ram is under the requirement, 0 otherwise.
Arguments:
-r, --required= : The amount to require, in Mb-f, --free : Count free RAM+swap-t, --total : Count total RAM+swap-s, --ignore_swap : Ignore swap, consider only real RAM-o, --only_swap : Ignore real RAM, consider only swapDetails:
Requires YunoHost version 3.8.1 or higher.
Usage: ynh_die --message=MSG [--ret_code=RETCODE]
Arguments:
-m, --message= : Message to display-c, --ret_code= : Exit code to exit withDetails:
Requires YunoHost version 2.4.0 or higher.
Usage: ynh_print_info --message="Some message"
Arguments:
-m, --message= : Message to displayDetails:
Requires YunoHost version 3.2.0 or higher.
Usage: ynh_print_warn --message="Text to print"
Arguments:
-m, --message= : The text to printDetails:
Requires YunoHost version 3.2.0 or higher.
Usage: ynh_print_err --message="Text to print"
Arguments:
-m, --message= : The text to printDetails:
Requires YunoHost version 3.2.0 or higher.
Usage: ynh_exec_err your_command
ynh_exec_err "your_command | other_command"
Arguments:
command : command to executeDetails:
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.If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.Requires YunoHost version 3.2.0 or higher.
Usage: ynh_exec_warn your_command
ynh_exec_warn "your_command | other_command"
Arguments:
command : command to executeDetails:
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.If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.Requires YunoHost version 3.2.0 or higher.
Usage: ynh_exec_warn_less your_command
ynh_exec_warn_less "your_command | other_command"
Arguments:
command : command to executeDetails:
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.If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.Requires YunoHost version 3.2.0 or higher.
Usage: ynh_exec_quiet your_command
ynh_exec_quiet "your_command | other_command"
Arguments:
command : command to executeDetails:
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.If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.Requires YunoHost version 3.2.0 or higher.
Usage: ynh_exec_fully_quiet your_command
ynh_exec_fully_quiet "your_command | other_command"
Arguments:
command : command to executeDetails:
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.If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.Requires YunoHost version 3.2.0 or higher.
Usage: ynh_print_OFF
Details:
WARNING: You should be careful with this helper, and never forget to use ynh_print_ON as soon as possible to restore the logging.Requires YunoHost version 3.2.0 or higher.
Usage: ynh_script_progression --message=message [--weight=weight] [--time]
Arguments:
-m, --message= : The text to print-w, --weight= : The weight for this progression. This value is 1 by default. Use a bigger value for a longer part of the script.-t, --time : Print the execution time since the last call to this helper. Especially usefull to define weights. The execution time is given for the duration since the previous call. So the weight should be applied to this previous call.-l, --last : Use for the last call of the helper, to fill the progression bar.Details:
Requires YunoHost version 3.5.0 or higher.
Usage: ynh_return somedata
Details:
Requires YunoHost version 3.6.0 or higher.
Usage: ynh_debug [--message=message] [--trace=1/0]
Arguments:
-m, --message= : The text to print-t, --trace= : Turn on or off the trace of the script. Usefull to trace nonly a small part of a script.Details:
Requires YunoHost version 3.5.0 or higher.
Usage: ynh_debug_exec your_command
ynh_debug_exec "your_command | other_command"
Arguments:
command : command to executeDetails:
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.If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.Requires YunoHost version 3.5.0 or higher.
Usage: ynh_use_logrotate [--logfile=/log/file] [--nonappend] [--specific_user=user/group]
Arguments:
-l, --logfile= : absolute path of logfile-n, --nonappend : (optional) Replace the config file instead of appending this new config.-u, --specific_user= : run logrotate as the specified user and group. If not specified logrotate is runned as root.Details:
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 :/parentdir/logdir/parentdir/logdir/logfile.logIt's possible to use this helper multiple times, each config will be added tothe same logrotate config file. Unless you use the option --non-appendRequires YunoHost version 2.6.4 or higher.Requires YunoHost version 3.2.0 or higher for the argument --specific_user
Usage: ynh_remove_logrotate
Details:
Requires YunoHost version 2.6.4 or higher.
Usage: ynh_mysql_connect_as --user=user --password=password [--database=database]
Arguments:
-u, --user= : the user name to connect as-p, --password= : the user password-d, --database= : the database to connect to
Example: ynh_mysql_connect_as --user="user" --password="pass" <<< "UPDATE ...;" example: ynh_mysql_connect_as --user="user" --password="pass" < /path/to/file.sql
Details:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_mysql_execute_as_root --sql=sql [--database=database]
Arguments:
-s, --sql= : the SQL command to execute-d, --database= : the database to connect toDetails:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_mysql_execute_file_as_root --file=file [--database=database]
Arguments:
-f, --file= : the file containing SQL commands-d, --database= : the database to connect toDetails:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_mysql_dump_db --database=database
Arguments:
-d, --database= : the database name to dumpReturns: the mysqldump output
Example: ynh_mysql_dump_db --database=roundcube > ./dump.sql
Details:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_mysql_user_exists --user=user
| exit: Return 1 if the user doesn't exist, 0 otherwise.
Arguments:
-u, --user= : the user for which to check existenceDetails:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_mysql_setup_db --db_user=user --db_name=name [--db_pwd=pwd]
Arguments:
-u, --db_user= : Owner of the database-n, --db_name= : Name of the database-p, --db_pwd= : Password of the database. If not provided, a password will be generatedDetails:
After executing this helper, the password of the created database will be available in $db_pwdIt will also be stored as "mysqlpwd" into the app settings.Requires YunoHost version 2.6.4 or higher.
Usage: ynh_mysql_remove_db --db_user=user --db_name=name
Arguments:
-u, --db_user= : Owner of the database-n, --db_name= : Name of the databaseDetails:
Requires YunoHost version 2.6.4 or higher.
Usage: ynh_find_port --port=begin_port
Arguments:
-p, --port= : port to start to searchReturns: the port number
Example: port=$(ynh_find_port --port=8080)
Details:
Requires YunoHost version 2.6.4 or higher.
Usage: ynh_find_port --port=XYZ
| exit: Return 1 if the port is already used by another process.
Arguments:
-p, --port= : port to check
Example: ynh_port_available --port=1234 || ynh_die "Port 1234 is needs to be available for this app"
Details:
Requires YunoHost version 3.8.0 or higher.
Usage: ynh_validate_ip4 --ip_address=ip_address
Arguments:
-i, --ip_address= : the ipv4 address to checkReturns: 0 for valid ipv4 addresses, 1 otherwise
Example: ynh_validate_ip4 111.222.333.444
Details:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_validate_ip6 --ip_address=ip_address
Arguments:
-i, --ip_address= : the ipv6 address to checkReturns: 0 for valid ipv6 addresses, 1 otherwise
Example: ynh_validate_ip6 2000:dead:beef::1
Details:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_add_nginx_config "list of others variables to replace"
Arguments:
list : (Optional) list of others variables to replace separated by spaces. For example : 'path_2 port_2 ...'Details:
This will use a template in ../conf/nginx.conf __PATH__ by $path_url __DOMAIN__ by $domain __PORT__ by $port __NAME__ by $app __FINALPATH__ by $final_path __PHPVERSION__ by $YNH_PHP_VERSION ($YNH_PHP_VERSION is either the default php version or the version defined for the app)And dynamic variables (from the last example) : __PATH_2__ by $path_2 __PORT_2__ by $port_2Requires YunoHost version 2.7.2 or higher.Requires YunoHost version 2.7.13 or higher for dynamic variables
Usage: ynh_remove_nginx_config
Details:
Requires YunoHost version 2.7.2 or higher.
Usage: ynh_use_nodejs
Details:
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.To use npm or node, use the alias `ynh_npm` and `ynh_node`Those alias will use the correct version installed for the appFor 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`And propagate $PATH to sudo with $ynh_node_load_PATHExemple: `ynh_exec_as $app $ynh_node_load_PATH $ynh_npm install`$PATH contains the path of the requested version of node.However, $PATH is duplicated into $node_PATH to outlast any manipulation of $PATHYou can use the variable `$ynh_node_load_PATH` to quickly load your node version in $PATH for an usage into a separate script.Exemple: $ynh_node_load_PATH $final_path/script_that_use_npm.sh`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. In such situation, you need to load PATH `Environment="__NODE_ENV_PATH__"` `ExecStart=__FINALPATH__/my_app` You will replace __NODE_ENV_PATH__ with $ynh_node_load_PATHOr 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_node2 other variables are also available - $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.Requires YunoHost version 2.7.12 or higher.
Usage: ynh_install_nodejs --nodejs_version=nodejs_version
Arguments:
-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.Details:
ynh_install_nodejs will install the version of node provided as argument by using n.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 versionRefer to ynh_use_nodejs for more information about available commands and variablesRequires YunoHost version 2.7.12 or higher.
Usage: ynh_remove_nodejs
Details:
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.
Usage: 1: ynh_add_fpm_config [--phpversion=7.X] [--use_template] [--package=packages] [--dedicated_service]
2: ynh_add_fpm_config [--phpversion=7.X] --usage=usage --footprint=footprint [--package=packages] [--dedicated_service]
low - Less than 20Mb of ram by pool.
medium - Between 20Mb and 40Mb of ram by pool.
high - More than 40Mb of ram by pool.
Or specify exactly the footprint, the load of the service as Mb by pool instead of having a standard value.
To have this value, use the following command and stress the service.
watch -n0.5 ps -o user,cmd,%cpu,rss -u APP
Arguments:
-v, --phpversion= : Version of php to use.-t, --use_template : Use this helper in template mode.-p, --package= : Additionnal php packages to install-d, --dedicated_service : Use a dedicated php-fpm service instead of the common one.-v, --phpversion= : Version of php to use.-f, --footprint= : Memory footprint of the service (low/medium/high).-u, --usage= : Expected usage of the service (low/medium/high).-p, --package= : Additionnal php packages to install for a specific version of php-d, --dedicated_service : Use a dedicated php-fpm service instead of the common one.Details:
-----------------------------------------------------------------------------The footprint of the service will be used to defined the maximum footprint we can allow, which is half the maximum RAM.So it will be used to defined 'pm.max_children'A lower value for the footprint will allow more children for 'pm.max_children'. And so for 'pm.start_servers', 'pm.min_spare_servers' and 'pm.max_spare_servers' which are defined from the value of 'pm.max_children'NOTE: 'pm.max_children' can't exceed 4 times the number of processor's cores.The usage value will defined the way php will handle the children for the pool.A value set as 'low' will set the process manager to 'ondemand'. Children will start only if the service is used, otherwise no child will stay alive. This config gives the lower footprint when the service is idle. But will use more proc since it has to start a child as soon it's used.Set as 'medium', the process manager will be at dynamic. If the service is idle, a number of children equal to pm.min_spare_servers will stay alive. So the service can be quick to answer to any request. The number of children can grow if needed. The footprint can stay low if the service is idle, but not null. The impact on the proc is a little bit less than 'ondemand' as there's always a few children already available.Set as 'high', the process manager will be set at 'static'. There will be always as many children as 'pm.max_children', the footprint is important (but will be set as maximum a quarter of the maximum RAM) but the impact on the proc is lower. The service will be quick to answer as there's always many children ready to answer.Requires YunoHost version 2.7.2 or higher.Requires YunoHost version 3.5.1 or higher for the argument --phpversionRequires YunoHost version 3.8.1 or higher for the arguments --use_template, --usage, --footprint, --package and --dedicated_service
Usage: ynh_remove_fpm_config
Details:
Requires YunoHost version 2.7.2 or higher.
Usage: ynh_psql_connect_as --user=user --password=password [--database=database]
Arguments:
-u, --user= : the user name to connect as-p, --password= : the user password-d, --database= : the database to connect toExamples:
ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;"
ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql
Details:
Requires YunoHost version 3.5.0 or higher.
Usage: ynh_psql_execute_as_root --sql=sql [--database=database]
Arguments:
-s, --sql= : the SQL command to execute-d, --database= : the database to connect toDetails:
Requires YunoHost version 3.5.0 or higher.
Usage: ynh_psql_execute_file_as_root --file=file [--database=database]
Arguments:
-f, --file= : the file containing SQL commands-d, --database= : the database to connect toDetails:
Requires YunoHost version 3.5.0 or higher.
Usage: ynh_psql_dump_db --database=database
Arguments:
-d, --database= : the database name to dumpReturns: the psqldump output
Example: ynh_psql_dump_db 'roundcube' > ./dump.sql
Details:
Requires YunoHost version 3.5.0 or higher.
Usage: ynh_psql_user_exists --user=user
| exit: Return 1 if the user doesn't exist, 0 otherwise
Arguments:
-u, --user= : the user for which to check existenceDetails:
Requires YunoHost version 3.5.0 or higher.
Usage: ynh_psql_database_exists --database=database
| exit: Return 1 if the database doesn't exist, 0 otherwise
Arguments:
-d, --database= : the database for which to check existenceDetails:
Requires YunoHost version 3.5.0 or higher.
Usage: ynh_psql_setup_db --db_user=user --db_name=name [--db_pwd=pwd]
Arguments:
-u, --db_user= : Owner of the database-n, --db_name= : Name of the database-p, --db_pwd= : Password of the database. If not given, a password will be generatedDetails:
After executing this helper, the password of the created database will be available in $db_pwdIt will also be stored as "psqlpwd" into the app settings.Requires YunoHost version 2.7.13 or higher.
Usage: ynh_psql_remove_db --db_user=user --db_name=name
Arguments:
-u, --db_user= : Owner of the database-n, --db_name= : Name of the databaseDetails:
Requires YunoHost version 2.7.13 or higher.
Usage: ynh_psql_test_if_first_run
Details:
Requires YunoHost version 2.7.13 or higher.
Usage: ynh_app_setting_get --app=app --key=key
Arguments:
-a, --app= : the application id-k, --key= : the setting to getDetails:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_app_setting_set --app=app --key=key --value=value
Arguments:
-a, --app= : the application id-k, --key= : the setting name to set-v, --value= : the setting value to setDetails:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_app_setting_delete --app=app --key=key
Arguments:
-a, --app= : the application id-k, --key= : the setting to deleteDetails:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_webpath_available --domain=domain --path_url=path
Arguments:
-d, --domain= : the domain/host of the url-p, --path_url= : the web path to check the availability of
Example: ynh_webpath_available --domain=some.domain.tld --path_url=/coffee
Details:
Requires YunoHost version 2.6.4 or higher.
Usage: ynh_webpath_register --app=app --domain=domain --path_url=path
Arguments:
-a, --app= : the app for which the domain should be registered-d, --domain= : the domain/host of the web path-p, --path_url= : the web path to be registered
Example: ynh_webpath_register --app=wordpress --domain=some.domain.tld --path_url=/coffee
Details:
Requires YunoHost version 2.6.4 or higher.
Usage: ynh_permission_create --permission "permission" [--url=url] [--allowed="group1 group2"]
Arguments:
-p, --permission= : the name for the permission (by default a permission named "main" already exist)-u, --url= : (optional) URL for which access will be allowed/forbidden-a, --allowed= : (optional) A list of group/user to allow for the permission
Example: ynh_permission_create --permission=admin --url=/admin --allowed="alice bob"
Details:
If provided, 'url' is assumed to be relative to the app domain/path if theystart with '/'. For example: / -> domain.tld/app /admin -> domain.tld/app/admin domain.tld/app/api -> domain.tld/app/api'url' can be later treated as a regex if it starts with "re:".For example: re:/api/[A-Z]*$ -> domain.tld/app/api/[A-Z]*$ re:domain.tld/app/api/[A-Z]*$ -> domain.tld/app/api/[A-Z]*$Requires YunoHost version 3.7.0 or higher.
Usage: ynh_permission_delete --permission="permission"
Arguments:
-p, --permission= : the name for the permission (by default a permission named "main" is removed automatically when the app is removed)
Example: ynh_permission_delete --permission=editors
Details:
Requires YunoHost version 3.7.0 or higher.
Usage: ynh_permission_exists --permission=permission
| exit: Return 1 if the permission doesn't exist, 0 otherwise
Arguments:
-p, --permission= : the permission to checkDetails:
Requires YunoHost version 3.7.0 or higher.
Usage: ynh_permission_url --permission="permission" [--url="url"]
Arguments:
-p, --permission= : the name for the permission (by default a permission named "main" is removed automatically when the app is removed)-u, --url= : (optional) URL for which access will be allowed/forbiddenDetails:
Requires YunoHost version 3.7.0 or higher.
Usage: ynh_permission_update --permission="permission" [--add="group1 group2"] [--remove="group1 group2"]
Arguments:
-p, --permission= : the name for the permission (by default a permission named "main" already exist)-a, --add= : the list of group or users to enable add to the permission-r, --remove= : the list of group or users to remove from the permission
Example: ynh_permission_update --permission admin --add=samdoe --remove=all_users
Details:
Requires YunoHost version 3.7.0 or higher.
Usage: ynh_permission_has_user --permission=permission --user=user
| exit: Return 1 if the permission doesn't have that user or doesn't exist, 0 otherwise
Arguments:
-p, --permission= : the permission to check-u, --user= : the user seek in the permission
Example: ynh_permission_has_user --permission=main --user=visitors
Details:
Requires YunoHost version 3.7.1 or higher.
Usage: ynh_string_random [--length=string_length]
Arguments:
-l, --length= : the string length to generate (default: 24)Returns: the generated string
Example: pwd=$(ynh_string_random --length=8)
Details:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_replace_string --match_string=match_string --replace_string=replace_string --target_file=target_file
Arguments:
-m, --match_string= : String to be searched and replaced in the file-r, --replace_string= : String that will replace matches-f, --target_file= : File in which the string will be replaced.Details:
As this helper is based on sed command, regular expressions andreferences to sub-expressions can be used(see sed manual page for more information)Requires YunoHost version 2.6.4 or higher.
Usage: ynh_replace_special_string --match_string=match_string --replace_string=replace_string --target_file=target_file
Arguments:
-m, --match_string= : String to be searched and replaced in the file-r, --replace_string= : String that will replace matches-t, --target_file= : File in which the string will be replaced.Details:
This helper will use ynh_replace_string, but as you can use specialcharacters, you can't use some regular expressions and sub-expressions.Requires YunoHost version 2.7.7 or higher.
Usage: ynh_sanitize_dbid --db_name=name
Arguments:
-n, --db_name= : name to correct/sanitizeReturns: the corrected name
Example: dbname=$(ynh_sanitize_dbid $app)
Details:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_add_systemd_config [--service=service] [--template=template]
ynh_add_systemd_config [--service=service] [--template=template] [--others_var="list of others variables to replace"]
Arguments:
-s, --service= : Service name (optionnal, $app by default)-t, --template= : Name of template file (optionnal, this is 'systemd' by default, meaning ./conf/systemd.service will be used as template)-v, --others_var= : List of others variables to replace separated by a space. For example: 'var_1 var_2 ...'Details:
This will use the template ../conf/
Usage: ynh_remove_systemd_config [--service=service]
Arguments:
-s, --service= : Service name (optionnal, $app by default)Details:
Requires YunoHost version 2.7.2 or higher.
Usage: ynh_systemd_action [--service_name=service_name] [--action=action] [ [--line_match="line to match"] [--log_path=log_path] [--timeout=300] [--length=20] ]
Arguments:
-n, --service_name= : Name of the service to start. Default : $app-a, --action= : Action to perform with systemctl. Default: start-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. WARNING: When using --line_match, you should always add `ynh_clean_check_starting` into your `ynh_clean_setup` at the beginning of the script. Otherwise, tail will not stop in case of failure of the script. The script will then hang forever.-p, --log_path= : Log file - Path to the log file. Default : /var/log/$app/$app.log-t, --timeout= : Timeout - The maximum time to wait before ending the watching. Default : 300 seconds.-e, --length= : Length of the error log : Default : 20Details:
Requires YunoHost version 3.5.0 or higher.
Usage: ynh_clean_check_starting
Details:
Requires YunoHost version 3.5.0 or higher.
Usage: ynh_user_exists --username=username
| exit: Return 1 if the user doesn't exist, 0 otherwise
Arguments:
-u, --username= : the username to check
Example: ynh_user_exists 'toto' || exit 1
Details:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_user_get_info --username=username --key=key
Arguments:
-u, --username= : the username to retrieve info from-k, --key= : the key to retrieveReturns: string - the key's value
Example: mail=$(ynh_user_get_info 'toto' 'mail')
Details:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_user_list
Returns: string - one username per line
Example: for u in $(ynh_user_list); do ...
Details:
Requires YunoHost version 2.4.0 or higher.
Usage: ynh_system_user_exists --username=username
| exit: Return 1 if the user doesn't exist, 0 otherwise
Arguments:
-u, --username= : the username to checkDetails:
Requires YunoHost version 2.2.4 or higher.
Usage: ynh_system_group_exists --group=group
| exit: Return 1 if the group doesn't exist, 0 otherwise
Arguments:
-g, --group= : the group to checkDetails:
Requires YunoHost version 3.5.0.2 or higher.
Usage: ynh_system_user_create --username=user_name [--home_dir=home_dir] [--use_shell]
Arguments:
-u, --username= : Name of the system user that will be create-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-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 shellExamples:
ynh_system_user_create --username=nextcloud
ynh_system_user_create --username=discourse --home_dir=/var/www/discourse --use_shell
Details:
Requires YunoHost version 2.6.4 or higher.
Usage: ynh_system_user_delete --username=user_name
Arguments:
-u, --username= : Name of the system user that will be createDetails:
Requires YunoHost version 2.6.4 or higher.
Usage: ynh_abort_if_errors
Details:
This configure the rest of the script execution such that, if an error occursor if an empty variable is used, the execution of the script stopsimmediately and a call to `ynh_clean_setup` is triggered if it has beendefined by your script.Requires YunoHost version 2.6.4 or higher.
Usage: ynh_setup_source --dest_dir=dest_dir [--source_id=source_id]
Arguments:
-d, --dest_dir= : Directory where to setup sources-s, --source_id= : Name of the app, if the package contains more than one appDetails:
The file conf/app.src need to contains:SOURCE_URL=Address to download the app archiveSOURCE_SUM=Control sum# (Optional) Program to check the integrity (sha256sum, md5sum...)# default: sha256SOURCE_SUM_PRG=sha256# (Optional) Archive format# default: tar.gzSOURCE_FORMAT=tar.gz# (Optional) Put false if sources are directly in the archive root# default: true# Instead of true, SOURCE_IN_SUBDIR could be the number of sub directories# to remove.SOURCE_IN_SUBDIR=false# (Optionnal) Name of the local archive (offline setup support)# default: ${src_id}.${src_format}SOURCE_FILENAME=example.tar.gz# (Optional) If it set as false don't extract the source.# (Useful to get a debian package or a python wheel.)# default: trueSOURCE_EXTRACT=(true|false)Details:This helper downloads sources from SOURCE_URL if there is no local sourcearchive in /opt/yunohost-apps-src/APP_ID/SOURCE_FILENAMENext, it checks the integrity with "SOURCE_SUM_PRG -c --status" command.If it's ok, the source archive will be uncompressed in $dest_dir. If theSOURCE_IN_SUBDIR is true, the first level directory of the archive will beremoved.If SOURCE_IN_SUBDIR is a numeric value, 2 for example, the 2 first leveldirectories will be removedFinally, patches named sources/patches/${src_id}-*.patch and extra files insources/extra_files/$src_id will be applied to dest_dirRequires YunoHost version 2.6.4 or higher.
Usage: ynh_local_curl "page_uri" "key1=value1" "key2=value2" ...
Arguments:
page_uri : Path (relative to $path_url) of the page where POST data will be sentkey1=value1 : (Optionnal) POST key and corresponding valuekey2=value2 : (Optionnal) Another POST key and corresponding value... : (Optionnal) More POST keys and values
Example: ynh_local_curl "/install.php?installButton" "foo=$var1" "bar=$var2"
Details:
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?))Requires YunoHost version 2.6.4 or higher.
Usage: ynh_get_debian_release
Returns: The Debian release codename (i.e. jessie, stretch, ...)
Details:
Requires YunoHost version 2.7.12 or higher.
Usage: ynh_secure_remove --file=path_to_remove
Arguments:
-f, --file= : File or directory to removeDetails:
Requires YunoHost version 2.6.4 or higher.
Usage: ynh_read_manifest --manifest="manifest.json" --key="key"
Arguments:
-m, --manifest= : Path of the manifest to read-k, --key= : Name of the key to findReturns: the value associate to that key
Details:
Requires YunoHost version 3.5.0 or higher.
Usage: ynh_app_upstream_version [--manifest="manifest.json"]
Arguments:
-m, --manifest= : Path of the manifest to readReturns: the version number of the upstream app
Details:
The version number in the manifest is defined by
Usage: ynh_app_package_version [--manifest="manifest.json"]
Arguments:
-m, --manifest= : Path of the manifest to readReturns: the version number of the package
Details:
The version number in the manifest is defined by
Usage: ynh_check_app_version_changed
Details:
- UPGRADE_APP if the upstream app version has changed- UPGRADE_PACKAGE if only the YunoHost package has changedIt stops the current script without error if the package is up-to-dateThis helper should be used to avoid an upgrade of an app, or the upstream partof it, when it's not neededTo force an upgrade, even if the package is up to date,you have to set the variable YNH_FORCE_UPGRADE before.example: sudo YNH_FORCE_UPGRADE=1 yunohost app upgrade MyAppRequires YunoHost version 3.5.0 or higher.