App helpers
Doc auto-generated by this script on 22/07/2023 (YunoHost version 11.2.3)
APPS
ynh_install_apps
Install others YunoHost apps
Usage: ynh_install_apps --apps="appfoo?domain=domain.foo&path=/foo appbar?domain=domain.bar&path=/bar&admin=USER&language=fr&is_public=1&pass?word=pass&port=666"
Arguments:
-a,--apps=: apps to install
Details:
Requires YunoHost version ..* or higher.
ynh_remove_apps
Remove other YunoHost apps
Usage: ynh_remove_apps
Details:
Other YunoHost apps will be removed only if no other apps need them.
Requires YunoHost version ..* or higher.
ynh_spawn_app_shell
Spawn a Bash shell with the app environment loaded
Usage: ynh_spawn_app_shell --app="app"
| arg: -a, --app= - the app ID
Examples:
ynh_spawn_app_shell --app="APP" <<< 'echo "$USER"'ynh_spawn_app_shell --app="APP" < /tmp/some_script.bash
Details:
Requires YunoHost version 11.0.* or higher, and that the app relies on packaging v2 or higher.
The spawned shell will have environment variables loaded and environment files sourced
from the app's service configuration file (defaults to $app.service, overridable by the packager with service setting).
If the app relies on a specific PHP version, then php will be aliased that version. The PHP command will also be appended with the phpflags settings.
APT
ynh_package_is_installed
Check either a package is installed or not
Usage: ynh_package_is_installed --package=name
Arguments:
-p,--package=: the package name to check
Returns: 0 if the package is installed, 1 else.
Example: ynh_package_is_installed --package=yunohost && echo "installed"
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_package_version
Get the version of an installed package
Usage: ynh_package_version --package=name
Arguments:
-p,--package=: the package name to get version
Returns: the version or an empty string
Example: version=$(ynh_package_version --package=yunohost)
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_package_update
Update package index files
ynh_package_install
Install package(s)
Usage: ynh_package_install name [name [...]]
Arguments:
name: the package name to install
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_package_remove
Remove package(s)
Usage: ynh_package_remove name [name [...]]
Arguments:
name: the package name to remove
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_package_autoremove
Remove package(s) and their uneeded dependencies
Usage: ynh_package_autoremove name [name [...]]
Arguments:
name: the package name to remove
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_package_autopurge
Purge package(s) and their uneeded dependencies
Usage: ynh_package_autopurge name [name [...]]
Arguments:
name: the package name to autoremove and purge
Details:
Requires YunoHost version 2.7.2 or higher.
ynh_install_app_dependencies
Define and install dependencies with a equivs control file
Usage: ynh_install_app_dependencies dep [dep [...]]
Arguments:
dep: the package name to install in dependence."dep1|dep2|…": You can specify alternatives. It will require to install (dep1 or dep2, etc).
Details:
This helper can/should only be called once per app
example : ynh_install_app_dependencies dep1 dep2 "dep3|dep4|dep5"
Requires YunoHost version 2.6.4 or higher.
ynh_add_app_dependencies
Add dependencies to install with ynh_install_app_dependencies
Usage: ynh_add_app_dependencies --package=phpversion [--replace]
Arguments:
-p,--package=: Packages to add as dependencies for the app.
Details:
Requires YunoHost version 3.8.1 or higher.
ynh_remove_app_dependencies
Remove fake package and its dependencies
Usage: ynh_remove_app_dependencies
Details:
Dependencies will removed only if no other package need them.
Requires YunoHost version 2.6.4 or higher.
ynh_install_extra_app_dependencies
Install packages from an extra repository properly.
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.
BACKUP
ynh_backup
Add a file or a directory to the list of paths to backup
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.
Details:
This helper can be used both in a system backup hook, and in an app backup script
ynh_backup writes src_path and the relative dest_path into a CSV file, and it
creates the parent destination directory
If dest_path is ended by a slash it complete this path with the basename of src_path.
Example in the context of a wordpress app :
ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf"
# => This line will be added into CSV file
# "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/etc/nginx/conf.d/$domain.d/$app.conf"
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"
How to use --is_big:
--is_big is used to specify that this part of the backup can be quite huge.
So, you don't want that your package does backup that part during ynh_backup_before_upgrade.
In the same way, an user may doesn't want to backup this big part of the app for
each of his backup. And so handle that part differently.
As this part of your backup may not be done, your restore script has to handle it.
In your restore script, use --not_mandatory with ynh_restore_file
As well in your remove script, you should not remove those data ! Or an user may end up with
a failed upgrade restoring an app without data anymore !
To have the benefit of --is_big while doing a backup, you can whether set the environement
variable BACKUP_CORE_ONLY to 1 (BACKUP_CORE_ONLY=1) before the backup command. It will affect
only that backup command.
Or set the config do_not_backup_data to 1 into the settings.yml of the app. This will affect
all backups for this app until the setting is removed.
Requires YunoHost version 2.4.0 or higher.
Requires YunoHost version 3.5.0 or higher for the argument --not_mandatory
ynh_restore
Restore all files that were previously backuped in a core backup script or app backup script
ynh_restore_file
Restore a file or a directory
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 beORIGIN_PATHor if theORIGIN_PATHdoesn't exist in the archive, the destination will be searched intobackup.csv-m,--not_mandatory: Indicate that if the file is missing, the restore process can ignore it.
Examples:
ynh_restore_file -o "/etc/nginx/conf.d/$domain.d/$app.conf"You can also use relative paths:ynh_restore_file -o "conf/nginx.conf"
Details:
Use the registered path in backup_list by ynh_backup to restore the file at the right place.
If DEST_PATH already exists and is lighter than 500 Mo, a backup will be made in
/var/cache/yunohost/appconfbackup/. Otherwise, the existing file is removed.
if apps/$app/etc/nginx/conf.d/$domain.d/$app.conf exists, restore it into
/etc/nginx/conf.d/$domain.d/$app.conf
if no, search for a match in the csv (eg: conf/nginx.conf) and restore it into
/etc/nginx/conf.d/$domain.d/$app.conf
Requires YunoHost version 2.6.4 or higher. Requires YunoHost version 3.5.0 or higher for the argument --not_mandatory
ynh_store_file_checksum
Calculate and store a file checksum into the app settings
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 helper
Requires YunoHost version 2.6.4 or higher.
ynh_backup_if_checksum_is_different
Verify the checksum and backup the file if it's different
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/manually
modified config files.
Requires YunoHost version 2.6.4 or higher.
ynh_delete_file_checksum
Delete a file checksum from the app settings
Usage: ynh_delete_file_checksum --file=file
Arguments:
-f,--file=: The file for which the checksum will be deleted
Details:
$app should be defined when calling this helper
Requires YunoHost version 3.3.1 or higher.
ynh_backup_before_upgrade
Make a backup in case of failed upgrade
Usage: ynh_backup_before_upgrade
Details:
Usage in a package script:
ynh_backup_before_upgrade
ynh_clean_setup () {
ynh_restore_upgradebackup
}
ynh_abort_if_errors
Requires YunoHost version 2.7.2 or higher.
ynh_restore_upgradebackup
Restore a previous backup if the upgrade process failed
Usage: ynh_restore_upgradebackup
Details:
Usage in a package script:
ynh_backup_before_upgrade
ynh_clean_setup () {
ynh_restore_upgradebackup
}
ynh_abort_if_errors
Requires YunoHost version 2.7.2 or higher.
CONFIG
FAIL2BAN
ynh_add_fail2ban_config
Create a dedicated fail2ban config (jail and filter conf files)
Usage: 1: ynh_add_fail2ban_config --logpath=log_file --failregex=filter [--max_retry=max_retry] [--ports=ports]
2: ynh_add_fail2ban_config --use_template
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
Details:
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
format and how placeholders are replaced with actual variables.
Generally 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 = 3
f2b_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+)\- <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 =
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 : https://www.fail2ban.org/wiki/index.php/MANUAL_0_8#Filters
Note that the logfile need to exist before to call this helper !!
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
Requires YunoHost version 4.1.0 or higher.
ynh_remove_fail2ban_config
Remove the dedicated fail2ban config (jail and filter conf files)
Usage: ynh_remove_fail2ban_config
Details:
Requires YunoHost version 3.5.0 or higher.
GETOPTS
HARDWARE
ynh_get_ram
Get the total or free amount of RAM+swap on the system
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 swap
Returns: the amount of free ram, in MB (MegaBytes)
Details:
Requires YunoHost version 3.8.1 or higher.
ynh_require_ram
Return 0 or 1 depending if the system has a given amount of RAM+swap free or total
Usage: ynh_require_ram --required=RAM [--free|--total] [--ignore_swap|--only_swap]
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 swap
Returns: 1 if the ram is under the requirement, 0 otherwise.
Details:
Requires YunoHost version 3.8.1 or higher.
LOGGING
ynh_die
Print a message to stderr and exit
Usage: ynh_die --message=MSG [--ret_code=RETCODE]
Arguments:
-m,--message=: Message to display-c,--ret_code=: Exit code to exit with
Details:
Requires YunoHost version 2.4.0 or higher.
ynh_print_info
Display a message in the 'INFO' logging category
Usage: ynh_print_info --message="Some message"
Arguments:
-m,--message=: Message to display
Details:
Requires YunoHost version 3.2.0 or higher.
ynh_print_warn
Print a warning on stderr
Usage: ynh_print_warn --message="Text to print"
Arguments:
-m,--message=: The text to print
Details:
Requires YunoHost version 3.2.0 or higher.
ynh_print_err
Print an error on stderr
Usage: ynh_print_err --message="Text to print"
Arguments:
-m,--message=: The text to print
Details:
Requires YunoHost version 3.2.0 or higher.
ynh_exec_err
Execute a command and print the result as an error
Usage: ynh_exec_err your command and args
Arguments:
command: command to execute
Details:
Note that you should NOT quote the command but only prefix it with ynh_exec_err
Requires YunoHost version 3.2.0 or higher.
ynh_exec_warn
Execute a command and print the result as a warning
Usage: ynh_exec_warn your command and args
Arguments:
command: command to execute
Details:
Note that you should NOT quote the command but only prefix it with ynh_exec_warn
Requires YunoHost version 3.2.0 or higher.
ynh_exec_warn_less
Execute a command and force the result to be printed on stdout
Usage: ynh_exec_warn_less your command and args
Arguments:
command: command to execute
Details:
Note that you should NOT quote the command but only prefix it with ynh_exec_warn
Requires YunoHost version 3.2.0 or higher.
ynh_exec_quiet
Execute a command and redirect stdout in /dev/null
Usage: ynh_exec_quiet your command and args
Arguments:
command: command to execute
Details:
Note that you should NOT quote the command but only prefix it with ynh_exec_warn
Requires YunoHost version 3.2.0 or higher.
ynh_exec_fully_quiet
Execute a command and redirect stdout and stderr in /dev/null
Usage: ynh_exec_quiet your command and args
Arguments:
command: command to execute
Details:
Note that you should NOT quote the command but only prefix it with ynh_exec_quiet
Requires YunoHost version 3.2.0 or higher.
ynh_script_progression
Print a progress bar showing the progression of an app script
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.
ynh_return
Return data to the YunoHost core for later processing (to be used by special hooks like app config panel and core diagnosis)
Usage: ynh_return somedata
Details:
Requires YunoHost version 3.6.0 or higher.
LOGROTATE
ynh_use_logrotate
Use logrotate to manage the logfile
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 point to a directory or a file.
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
Requires YunoHost version 2.6.4 or higher.
Requires YunoHost version 3.2.0 or higher for the argument --specific_user
ynh_remove_logrotate
Remove the app's logrotate config.
Usage: ynh_remove_logrotate
Details:
Requires YunoHost version 2.6.4 or higher.
MULTIMEDIA
ynh_multimedia_build_main_dir
Initialize the multimedia directory system
Usage: ynh_multimedia_build_main_dir
Details:
Requires YunoHost version 4.2 or higher.
ynh_multimedia_addfolder
Add a directory in yunohost.multimedia
Usage: ynh_multimedia_addfolder --source_dir="source_dir" --dest_dir="dest_dir"
Arguments:
-s,--source_dir=: Source directory - The real directory which contains your medias.-d,--dest_dir=: Destination directory - The name and the place of the symbolic link, relative to "/home/yunohost.multimedia"
Details:
This "directory" will be a symbolic link to a existing directory.
Requires YunoHost version 4.2 or higher.
ynh_multimedia_addaccess
Allow an user to have an write authorisation in multimedia directories
Usage: ynh_multimedia_addaccess user_name
Arguments:
-u,--user_name=: The name of the user which gain this access.
Details:
Requires YunoHost version 4.2 or higher.
MYSQL
ynh_mysql_connect_as
Open a connection as a user
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
Examples:
ynh_mysql_connect_as --user="user" --password="pass" <<< "UPDATE ...;"ynh_mysql_connect_as --user="user" --password="pass" < /path/to/file.sql
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_mysql_execute_as_root
Execute a command as root user
Usage: ynh_mysql_execute_as_root --sql=sql [--database=database]
Arguments:
-s,--sql=: the SQL command to execute-d,--database=: the database to connect to
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_mysql_execute_file_as_root
Execute a command from a file as root user
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 to
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_mysql_dump_db
Dump a database
Usage: ynh_mysql_dump_db --database=database
Arguments:
-d,--database=: the database name to dump
Returns: The mysqldump output
Example: ynh_mysql_dump_db --database=roundcube > ./dump.sql
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_mysql_user_exists
Check if a mysql user exists
Usage: ynh_mysql_user_exists --user=user
Arguments:
-u,--user=: the user for which to check existence
Returns: 0 if the user exists, 1 otherwise.
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_mysql_setup_db
Create a database, an user and its password. Then store the password in the app's config
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 generated
Details:
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.
Requires YunoHost version 2.6.4 or higher.
ynh_mysql_remove_db
Remove a database if it exists, and the associated user
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 database
Details:
Requires YunoHost version 2.6.4 or higher.
NETWORK
ynh_find_port
Find a free port and return it
Usage: ynh_find_port --port=begin_port
Arguments:
-p,--port=: port to start to search
Returns: the port number
Example: port=$(ynh_find_port --port=8080)
Details:
Requires YunoHost version 2.6.4 or higher.
ynh_port_available
Test if a port is available
Usage: ynh_find_port --port=XYZ
Arguments:
-p,--port=: port to check
Returns: 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"
Details:
Requires YunoHost version 3.8.0 or higher.
ynh_validate_ip4
Validate an IPv4 address
Usage: ynh_validate_ip4 --ip_address=ip_address
Arguments:
-i,--ip_address=: the ipv4 address to check
Returns: 0 for valid ipv4 addresses, 1 otherwise
Example: ynh_validate_ip4 111.222.333.444
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_validate_ip6
Validate an IPv6 address
Usage: ynh_validate_ip6 --ip_address=ip_address
Arguments:
-i,--ip_address=: the ipv6 address to check
Returns: 0 for valid ipv6 addresses, 1 otherwise
Example: ynh_validate_ip6 2000:dead:beef::1
Details:
Requires YunoHost version 2.2.4 or higher.
NGINX
ynh_add_nginx_config
Create a dedicated nginx config
Usage: ynh_add_nginx_config
Details:
This will use a template in ../conf/nginx.conf
See the documentation of ynh_add_config for a description of the template
format and how placeholders are replaced with actual variables.
Additionally, ynh_add_nginx_config will replace:
#sub_path_onlyby empty string ifpath_urlis not'/'#root_path_onlyby empty string ifpath_urlis'/'
This allows to enable/disable specific behaviors dependenging on the install location
Requires YunoHost version 4.1.0 or higher.
ynh_remove_nginx_config
Remove the dedicated nginx config
Usage: ynh_remove_nginx_config
Details:
Requires YunoHost version 2.7.2 or higher.
ynh_change_url_nginx_config
Move / regen the nginx config in a change url context
Usage: ynh_change_url_nginx_config
Details:
Requires YunoHost version 11.1.9 or higher.
NODEJS
ynh_use_nodejs
Load the version of node for an app, and set variables.
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 app.
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
And propagate $PATH to sudo with $ynh_node_load_PATH
Exemple: 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 $PATH
You 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_PATH.
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
2 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.
ynh_install_nodejs
Install a specific version of nodejs
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 version
Refer to ynh_use_nodejs for more information about available commands and variables
Requires YunoHost version 2.7.12 or higher.
ynh_remove_nodejs
Remove the version of node used by the app.
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.
PERMISSION
ynh_permission_create
Create a new permission for the app
Usage: ynh_permission_create --permission="permission" [--url="url"] [--additional_urls="second-url" [ "third-url" ]] [--auth_header=true|false]
[--allowed=group1 [ group2 ]] [--label="label"] [--show_tile=true|false]
[--protected=true|false]
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. Note that if 'show_tile' is enabled, this URL will be the URL of the tile.-A,--additional_urls=: (optional) List of additional URL for which access will be allowed/forbidden-h,--auth_header=: (optional) Define for the URL of this permission, if SSOwat pass the authentication header to the application. Default is true-a,--allowed=: (optional) A list of group/user to allow for the permission-l,--label=: (optional) Define a name for the permission. This label will be shown on the SSO and in the admin. Default is "APP_LABEL (permission name)".-t,--show_tile=: (optional) Define if a tile will be shown in the SSO. If yes the name of the tile will be the 'label' parameter. Defaults to false for the permission different than 'main'.-P,--protected=: (optional) Define if this permission is protected. If it is protected the administrator won't be able to add or remove the visitors group of this permission. Defaults to 'false'.
Details:
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
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'.
- 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 \ --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. In case of an API with need to be always public it avoid that the admin break anything. With this permission all client will be allowed to access to the url 'domain.tld/api'. Note that in this case no tile will be show on the SSO. Note that the auth_header parameter is to 'false'. So no authentication header will be passed to the application. Generally the API is requested by an application and enabling the auth_header has no advantage and could bring some issues in some case. So in this case it's better to disable this option for all API.
If provided, 'url' or 'additional_urls' is assumed to be relative to the app domain/path if they start with '/'. For example: / -> domain.tld/app /admin -> domain.tld/app/admin 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:". 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]$
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 used for the url of tile in the SSO (if enabled with the 'show_tile' parameter)
About the authentication header (auth_header parameter). The SSO pass (by default) to the application theses following HTTP header (linked to the authenticated user) to the application:
- "Auth-User": username
- "Remote-User": username
- "Email": user email
Generally this feature is usefull to authenticate automatically the user in the application but in some case the application don't work with theses header and theses header need to be disabled to have the application to work correctly. See https://github.com/YunoHost/issues/issues/1420 for more informations
Requires YunoHost version 3.7.0 or higher.
ynh_permission_delete
Remove a permission for the app (note that when the app is removed all permission is automatically removed)
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.
ynh_permission_exists
Check if a permission exists
Usage: ynh_permission_exists --permission=permission
| exit: Return 1 if the permission doesn't exist, 0 otherwise
Arguments:
-p,--permission=: the permission to check
Details:
Requires YunoHost version 3.7.0 or higher.
ynh_permission_url
Redefine the url associated to a permission
Usage: ynh_permission_url --permission "permission" [--url="url"] [--add_url="new-url" [ "other-new-url" ]] [--remove_url="old-url" [ "other-old-url" ]]
[--auth_header=true|false] [--clear_urls]
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/forbidden. Note that if you want to remove url you can pass an empty sting as arguments ("").-a,--add_url=: (optional) List of additional url to add for which access will be allowed/forbidden.-r,--remove_url=: (optional) List of additional url to remove for which access will be allowed/forbidden-h,--auth_header=: (optional) Define for the URL of this permission, if SSOwat pass the authentication header to the application-c,--clear_urls: (optional) Clean all urls (url and additional_urls)
Details:
Requires YunoHost version 3.7.0 or higher.
ynh_permission_update
Update a permission for the app
Usage: ynh_permission_update --permission "permission" [--add="group" ["group" ...]] [--remove="group" ["group" ...]]
[--label="label"] [--show_tile=true|false] [--protected=true|false]
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-l,--label=: (optional) Define a name for the permission. This label will be shown on the SSO and in the admin.-t,--show_tile=: (optional) Define if a tile will be shown in the SSO-P,--protected=: (optional) Define if this permission is protected. If it is protected the administrator won't be able to add or remove the visitors group of this permission.
Details:
Requires YunoHost version 3.7.0 or higher.
ynh_permission_has_user
Check if a permission has an user
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.
ynh_legacy_permissions_exists
Check if a legacy permissions exist
Usage: ynh_legacy_permissions_exists
| exit: Return 1 if the permission doesn't exist, 0 otherwise
Details:
Requires YunoHost version 4.1.2 or higher.
ynh_legacy_permissions_delete_all
Remove all legacy permissions
Usage: ynh_legacy_permissions_delete_all
Example: if ynh_legacy_permissions_exists then ynh_legacy_permissions_delete_all # You can recreate the required permissions here with ynh_permission_create fi Requires YunoHost version 4.1.2 or higher.
PHP
ynh_add_fpm_config
Create a dedicated PHP-FPM config
Usage: ynh_add_fpm_config
Details:
Case 1 (recommended) : your provided a snippet conf/extra_php-fpm.conf
The actual PHP configuration will be automatically generated, and your extra_php-fpm.conf will be appended (typically contains PHP upload limits)
The resulting configuration will be deployed to the appropriate place, /etc/php/$phpversion/fpm/pool.d/$app.conf
Performance-related options in the PHP conf, such as : pm.max_children, pm.start_servers, pm.min_spare_servers pm.max_spare_servers are computed from two parameters called "usage" and "footprint" which can be set to low/medium/high. (cf details below)
If you wish to tweak those, please initialize the settings fpm_usage and fpm_footprint
prior to calling this helper. Otherwise, "low" will be used as a default for both values.
Otherwise, if you want the user to have control over these, we encourage to create a config panel (which should ultimately be standardized by the core ...)
Case 2 (deprecate) : you provided an entire conf/php-fpm.conf
The configuration will be hydrated, replacing FOOBAR placeholders with $foobar values, etc.
The resulting configuration will be deployed to the appropriate place, /etc/php/$phpversion/fpm/pool.d/$app.conf
fpm_footprint: Memory footprint of the service (low/medium/high). low - Less than 20 MB of RAM by pool. medium - Between 20 MB and 40 MB of RAM by pool. high - More than 40 MB of RAM by pool. N - Or you can specify a quantitative footprint as MB by pool (use watch -n0.5 ps -o user,cmd,%cpu,rss -u APP)
fpm_usage: Expected usage of the service (low/medium/high). low - Personal usage, behind the SSO. medium - Low usage, few people or/and publicly accessible. high - High usage, frequently visited website.
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 4.1.0 or higher.
ynh_remove_fpm_config
Remove the dedicated PHP-FPM config
Usage: ynh_remove_fpm_config
Details:
Requires YunoHost version 2.7.2 or higher.
ynh_composer_exec
Execute a command with Composer
Usage: ynh_composer_exec [--phpversion=phpversion] [--workdir=$install_dir] --commands="commands"
Arguments:
-v,--phpversion: PHP version to use with composer-w,--workdir: The directory from where the command will be executed. Default $install_dir or $final_path-c,--commands: Commands to execute.
Details:
Requires YunoHost version 4.2 or higher.
ynh_install_composer
Install and initialize Composer in the given directory
Usage: ynh_install_composer [--phpversion=phpversion] [--workdir=$install_dir] [--install_args="--optimize-autoloader"] [--composerversion=composerversion]
Arguments:
-v,--phpversion: PHP version to use with composer-w,--workdir: The directory from where the command will be executed. Default $install_dir.-a,--install_args: Additional arguments provided to the composer install. Argument --no-dev already include-c,--composerversion: Composer version to install
Details:
Requires YunoHost version 4.2 or higher.
POSTGRESQL
ynh_psql_connect_as
Open a connection as a user
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 to
Examples:
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.
ynh_psql_execute_as_root
Execute a command as root user
Usage: ynh_psql_execute_as_root --sql=sql [--database=database]
Arguments:
-s,--sql=: the SQL command to execute-d,--database=: the database to connect to
Details:
Requires YunoHost version 3.5.0 or higher.
ynh_psql_execute_file_as_root
Execute a command from a file as root user
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 to
Details:
Requires YunoHost version 3.5.0 or higher.
ynh_psql_dump_db
Dump a database
Usage: ynh_psql_dump_db --database=database
Arguments:
-d,--database=: the database name to dump
Returns: the psqldump output
Example: ynh_psql_dump_db 'roundcube' > ./dump.sql
Details:
Requires YunoHost version 3.5.0 or higher.
ynh_psql_user_exists
Check if a psql user exists
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 existence
Details:
Requires YunoHost version 3.5.0 or higher.
ynh_psql_database_exists
Check if a psql database exists
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 existence
Details:
Requires YunoHost version 3.5.0 or higher.
ynh_psql_setup_db
Create a database, an user and its password. Then store the password in the app's config
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 provided, a password will be generated
Details:
After executing this helper, the password of the created database will be available in $db_pwd
It will also be stored as "psqlpwd" into the app settings.
Requires YunoHost version 2.7.13 or higher.
ynh_psql_remove_db
Remove a database if it exists, and the associated user
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 database
Details:
Requires YunoHost version 2.7.13 or higher.
SETTING
ynh_app_setting_get
Get an application setting
Usage: ynh_app_setting_get --app=app --key=key
Arguments:
-a,--app=: the application id-k,--key=: the setting to get
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_app_setting_set
Set an application setting
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 set
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_app_setting_delete
Delete an application setting
Usage: ynh_app_setting_delete --app=app --key=key
Arguments:
-a,--app=: the application id-k,--key=: the setting to delete
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_webpath_available
Check availability of a web path
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.
ynh_webpath_register
Register/book a web path for an app
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.
STRING
ynh_string_random
Generate a random string
Usage: ynh_string_random [--length=string_length]
Arguments:
-l,--length=: the string length to generate (default: 24)-f,--filter=: the kind of characters accepted in the output (default: 'A-Za-z0-9')
Returns: the generated string
Example: pwd=$(ynh_string_random --length=8)
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_replace_string
Substitute/replace a string (or expression) by another in a file
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 and references to
sub-expressions can be used (see sed manual page for more information)
Requires YunoHost version 2.6.4 or higher.
ynh_replace_special_string
Substitute/replace a special string by another in a file
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 special
characters, you can't use some regular expressions and sub-expressions.
Requires YunoHost version 2.7.7 or higher.
ynh_sanitize_dbid
Sanitize a string intended to be the name of a database
Usage: ynh_sanitize_dbid --db_name=name
Arguments:
-n,--db_name=: name to correct/sanitize
Returns: the corrected name
Example: dbname=$(ynh_sanitize_dbid $app)
Details:
Underscorify the string (replace - and . by _)
Requires YunoHost version 2.2.4 or higher.
SYSTEMD
ynh_add_systemd_config
Create a dedicated systemd config
Usage: ynh_add_systemd_config [--service=service] [--template=template]
Arguments:
-s,--service=: Service name (optionnal,$appby default)-t,--template=: Name of template file (optionnal, this is 'systemd' by default, meaning../conf/systemd.servicewill be used as template)
Details:
This will use the template ../conf/<templatename>.service.
See the documentation of ynh_add_config for a description of the template
format and how placeholders are replaced with actual variables.
Requires YunoHost version 4.1.0 or higher.
ynh_remove_systemd_config
Remove the dedicated systemd config
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.
ynh_systemd_action
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] ]
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.-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 displayed for debugging : Default : 20
Details:
Requires YunoHost version 3.5.0 or higher.
USER
ynh_user_exists
Check if a YunoHost user exists
Usage: ynh_user_exists --username=username
Arguments:
-u,--username=: the username to check
Returns: 0 if the user exists, 1 otherwise.
Example: ynh_user_exists 'toto' || echo "User does not exist"
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_user_get_info
Retrieve a YunoHost user information
Usage: ynh_user_get_info --username=username --key=key
Arguments:
-u,--username=: the username to retrieve info from-k,--key=: the key to retrieve
Returns: the value associate to that key
Example: mail=$(ynh_user_get_info --username="toto" --key=mail)
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_user_list
Get the list of YunoHost users
Usage: ynh_user_list
Returns: one username per line as strings
Example: for u in $(ynh_user_list); do ... ; done
Details:
Requires YunoHost version 2.4.0 or higher.
ynh_system_user_exists
Check if a user exists on the system
Usage: ynh_system_user_exists --username=username
Arguments:
-u,--username=: the username to check
Returns: 0 if the user exists, 1 otherwise.
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_system_group_exists
Check if a group exists on the system
Usage: ynh_system_group_exists --group=group
Arguments:
-g,--group=: the group to check
Returns: 0 if the group exists, 1 otherwise.
Details:
Requires YunoHost version 3.5.0.2 or higher.
ynh_system_user_create
Create a system user
Usage: ynh_system_user_create --username=user_name [--home_dir=home_dir] [--use_shell] [--groups="group1 group2"]
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 shell-g,--groups: Add the user to system groups. Typically meant to add the user to the ssh.app / sftp.app group (e.g. for borgserver, my_webapp)
Details:
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.
ynh_system_user_delete
Delete a system user
Usage: ynh_system_user_delete --username=user_name
Arguments:
-u,--username=: Name of the system user that will be create
Details:
Requires YunoHost version 2.6.4 or higher.
ynh_exec_as
Execute a command as another user
Usage: ynh_exec_as $USER COMMAND [ARG ...]
Details:
Requires YunoHost version 4.1.7 or higher.
UTILS
ynh_abort_if_errors
Exits if an error occurs during the execution of the script.
Usage: ynh_abort_if_errors
Details:
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 immediately
and a call to ynh_clean_setup is triggered if it has been defined by your script.
Requires YunoHost version 2.6.4 or higher.
ynh_setup_source
Download, check integrity, uncompress and patch the source from app.src
Usage: ynh_setup_source --dest_dir=dest_dir [--source_id=source_id] [--keep="file1 file2"] [--full_replace]
Arguments:
-d,--dest_dir=: Directory where to setup sources-s,--source_id=: Name of the source, defaults tomain(when the sources resource exists in manifest.toml) or (legacy)appotherwise-k,--keep=: Space-separated list of files/folders that will be backup/restored in $dest_dir, such as a config file you don't want to overwrite. For example 'conf.json secrets.json logs/'-r,--full_replace=: Remove previous sources before installing new sources
Details:
New 'sources' resources
(See also the resources documentation which may be more complete?)
This helper will read infos from the 'sources' resources in the manifest.toml of the app and expect a structure like:
[resources.sources]
[resources.sources.main]
url = "https://some.address.to/download/the/app/archive"
sha256 = "0123456789abcdef" # The sha256 sum of the asset obtained from the URL
Optional flags
format = "tar.gz"/xz/bz2 # automatically guessed from the extension of the URL, but can be set explicitly. Will use `tar` to extract
"zip" # automatically guessed from the extension of the URL, but can be set explicitly. Will use `unzip` to extract
"docker" # useful to extract files from an already-built docker image (instead of rebuilding them locally). Will use `docker-image-extract` to extract
"whatever" # an arbitrary value, not really meaningful except to imply that the file won't be extracted
in_subdir = true # default, there's an intermediate subdir in the archive before accessing the actual files
false # sources are directly in the archive root
n # (special cases) an integer representing a number of subdirs levels to get rid of
extract = true # default if file is indeed an archive such as .zip, .tar.gz, .tar.bz2, ...
= false # default if file 'format' is not set and the file is not to be extracted because it is not an archive but a script or binary or whatever asset.
# in which case the file will only be `mv`ed to the location possibly renamed using the `rename` value
rename = "whatever_your_want" # to be used for convenience when `extract` is false and the default name of the file is not practical
platform = "linux/amd64" # (defaults to "linux/$YNH_ARCH") to be used in conjonction with `format = "docker"` to specify which architecture to extract for
You may also define assets url and checksum per-architectures such as:
[resources.sources]
[resources.sources.main]
amd64.url = "https://some.address.to/download/the/app/archive/when/amd64"
amd64.sha256 = "0123456789abcdef"
armhf.url = "https://some.address.to/download/the/app/archive/when/armhf"
armhf.sha256 = "fedcba9876543210"
In which case ynh_setup_source --dest_dir="$install_dir" will automatically pick the appropriate source depending on the arch
Legacy format '.src'
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_SUM=Sha256 sum
SOURCE_FORMAT=tar.gz
SOURCE_IN_SUBDIR=false
SOURCE_FILENAME=example.tar.gz
SOURCE_EXTRACT=(true|false)
SOURCE_PLATFORM=linux/arm64/v8
The helper will:
- Download the specific URL if there is no local archive
- Check the integrity with the specific sha256 sum
- Uncompress the archive to
$dest_dir.- If
in_subdiris true, the first level directory of the archive will be removed. - If
in_subdiris a numeric value, the N first level directories will be removed.
- If
- Patches named
sources/patches/${src_id}-*.patchwill be applied to$dest_dir - Extra files in
sources/extra_files/$src_idwill be copied to dest_dir
Requires YunoHost version 2.6.4 or higher.
ynh_local_curl
Curl abstraction to help with POST requests to local pages (such as installation forms)
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.
ynh_add_config
Create a dedicated config file from a template
Usage: ynh_add_config --template="template" --destination="destination"
Arguments:
-t,--template=: Template config file to use-d,--destination=: Destination of the config file
Examples:
ynh_add_config --template=".env" --destination="$install_dir/.env" use the template file "../conf/.env"ynh_add_config --template="/etc/nginx/sites-available/default" --destination="etc/nginx/sites-available/mydomain.conf"
Details:
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.
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 :
__PATH__ by $path_url
__NAME__ by $app
__NAMETOCHANGE__ by $app
__USER__ by $app
__FINALPATH__ by $final_path
__PHPVERSION__ by $YNH_PHP_VERSION (packaging v1 only, packaging v2 uses phpversion setting implicitly set by apt resource)
__YNH_NODE_LOAD_PATH__ by $ynh_node_load_PATH
And any dynamic variables that should be defined before calling this helper like:
__DOMAIN__ by $domain
__APP__ by $app
__VAR_1__ by $var_1
__VAR_2__ by $var_2
The helper will verify the checksum and backup the destination file if it's different before applying the new template.
And it will calculate and store the destination file checksum into the app settings when configuration is done.
Requires YunoHost version 4.1.0 or higher.
ynh_read_var_in_file
Get a value from heterogeneous file (yaml, json, php, python...)
Usage: ynh_read_var_in_file --file=PATH --key=KEY
Arguments:
-f,--file=: the path to the file-k,--key=: the key to get
Details:
This helpers match several var affectation use case in several languages
We don't use jq or equivalent to keep comments and blank space in files
This helpers work line by line, it is not able to work correctly
if you have several identical keys in your files
Example of line this helpers can managed correctly .yml title: YunoHost documentation email: 'yunohost@yunohost.org' .json "theme": "colib'ris", "port": 8102 "some_boolean": false, "user": null .ini some_boolean = On action = "Clear" port = 20 .php $user= user => 20 .py USER = 8102 user = 'https://donate.local' CUSTOM['user'] = 'YunoHost'
Requires YunoHost version 4.3 or higher.
ynh_write_var_in_file
Set a value into heterogeneous file (yaml, json, php, python...)
Usage: ynh_write_var_in_file --file=PATH --key=KEY --value=VALUE
Arguments:
-f,--file=: the path to the file-k,--key=: the key to set-v,--value=: the value to set
Details:
Requires YunoHost version 4.3 or higher.
ynh_get_debian_release
Fetch the Debian release codename
Usage: ynh_get_debian_release
Returns: The Debian release codename (i.e. jessie, stretch, ...)
Details:
Requires YunoHost version 2.7.12 or higher.
ynh_secure_remove
Remove a file or a directory securely
Usage: ynh_secure_remove --file=path_to_remove
Arguments:
-f,--file=: File or directory to remove
Details:
Requires YunoHost version 2.6.4 or higher.
ynh_read_manifest
Read the value of a key in a ynh manifest file
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 find
Returns: the value associate to that key
Details:
Requires YunoHost version 3.5.0 or higher.
ynh_app_upstream_version
Read the upstream version from the manifest or `$YNH_APP_MANIFEST_VERSION`
Usage: ynh_app_upstream_version [--manifest="manifest.json"]
Arguments:
-m,--manifest=: Path of the manifest to read
Returns: the version number of the upstream app
Details:
If the manifest is not specified, the envvar $YNH_APP_MANIFEST_VERSION will be used.
The version number in the manifest is defined by <upstreamversion>~ynh<packageversion>.
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.
ynh_app_package_version
Read package version from the manifest
Usage: ynh_app_package_version [--manifest="manifest.json"]
Arguments:
-m,--manifest=: Path of the manifest to read
Returns: the version number of the package
Details:
The version number in the manifest is defined by <upstreamversion>~ynh<packageversion>.
For example, if the manifest contains 4.3-2~ynh3 the function will return 3
Requires YunoHost version 3.5.0 or higher.
ynh_check_app_version_changed
Checks the app version to upgrade with the existing app version and returns:
Usage: ynh_check_app_version_changed
Returns: UPGRADE_APP if the upstream version changed, UPGRADE_PACKAGE otherwise.
Details:
This helper should be used to avoid an upgrade of an app, or the upstream part
of it, when it's not needed
You can force an upgrade, even if the package is up to date, with the --force (or -F) argument :
sudo yunohost app upgrade <appname> --force
Requires YunoHost version 3.5.0 or higher.
ynh_compare_current_package_version
Compare the current package version against another version given as an argument.
Usage: ynh_compare_current_package_version --comparison (lt|le|eq|ne|ge|gt) --version <X~ynhY>
Arguments:
--comparison: Comparison type. Could be :lt(lower than),le(lower or equal),eq(equal),ne(not equal),ge(greater or equal),gt(greater than)--version: The version to compare. Need to be a version in the yunohost package version type (like2.3.1~ynh4)
Returns: 0 if the evaluation is true, 1 if false.
Example: ynh_compare_current_package_version --comparison lt --version 2.3.2~ynh1
Details:
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
then
# Do something that is needed for the package version older than 2.3.2~ynh1
fi
Requires YunoHost version 3.8.0 or higher.