121 KiB
App helpers
backend
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 be just a directory, or a full path to a logfile :
/parentdir/logdir
/parentdir/logdir/logfile.log
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.
ynh_remove_logrotate
Remove the app's logrotate config.
Usage: ynh_remove_logrotate
Details:
Requires YunoHost version 2.6.4 or higher.
ynh_add_systemd_config
Create a dedicated systemd config
Usage: ynh_add_systemd_config [--service=service] [--template=template]
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)
Details:
This will use the template ../conf/.service
to generate a systemd config, by replacing the following keywords
with global variables that should be defined before calling
this helper :
__APP__ by $app
__FINALPATH__ by $final_path
Requires YunoHost version 2.7.2 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_add_nginx_config
Create a dedicated nginx config
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
And dynamic variables (from the last example) :
__PATH_2__ by $path_2
__PORT_2__ by $port_2
Requires YunoHost version 2.7.2 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_add_fpm_config
Create a dedicated php-fpm config
Usage: ynh_add_fpm_config [--phpversion=7.X]
Arguments:
-v,--phpversion: Version of php to use.
Details:
Requires YunoHost version 2.7.2 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_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 [--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 space
Details:
-----------------------------------------------------------------------------
This will use a template in ../conf/f2b_jail.conf and ../conf/f2b_filter.conf
__APP__ by $app
You can dynamically replace others variables by example :
__VAR_1__ by $var_1
__VAR_2__ by $var_2
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+)\- \- \d+ \- Received request\: POST /_matrix/client/r0/login\??%(__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'%(__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 "" can
be used for standard IP/hostname matching and is only an alias for
(?:::f{4,6}:)?(?P[\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 3.?.? 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.?.? or higher.
debug
ynh_debug
Debugger for app packagers
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.?.? or higher.
ynh_debug_exec
Execute a command and print the result as debug
Usage: ynh_debug_exec command to execute
ynh_debug_exec "command to execute | following command"
In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe.
Arguments:
command: command to execute
Details:
Requires YunoHost version 3.?.? or higher.
filesystem
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.arg: Deprecated arg
Details:
Note: this helper could be used in backup hook or in backup script inside an
app package
Details: ynh_backup writes SRC and the relative DEST into a CSV file. And it
creates the parent destination directory
If DEST is ended by a slash it complete this path with the basename of SRC.
Example in the context of a wordpress app
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"
Requires YunoHost version 2.4.0 or higher.
ynh_restore
Restore all files linked to the restore hook or to the restore app 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 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"
You can also use relative paths:
ynh_restore_file "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
/home/yunohost.conf/backup/. Otherwise, the existing file is removed.
if apps/wordpress/etc/nginx/conf.d/$domain.d/$app.conf exists, restore it into
/etc/nginx/conf.d/$domain.d/$app.conf
if 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.
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 This helper is primarily meant to allow to easily backup personalised/manually modified config files.
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:
$app should be defined when calling this helper
Requires YunoHost version 2.6.4 or higher.
ynh_delete_file_checksum
Delete a file checksum from the app settings
Usage: ynh_remove_file_checksum 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_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.
getopts
ip
ynh_validate_ip
Validate an IP address
Usage: ynh_validate_ip --family=family --ip_address=ip_address
Returns: 0 for valid ip addresses, 1 otherwise
Example: ynh_validate_ip 4 111.222.333.444
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_validate_ip4
Validate an IPv4 address
Usage: ynh_validate_ip4 --ip_address=ip_address
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
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.
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
Example: ynh_mysql_connect_as 'user' 'pass' <<< "UPDATE ...;" example: ynh_mysql_connect_as 'user' '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 '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
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.
ynh_sanitize_dbid
Sanitize a string intended to be the name of a database (More specifically : replace - and . by _)
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:
Requires YunoHost version 2.2.4 or higher.
network
ynh_normalize_url_path
Normalize the url path syntax
Usage: ynh_normalize_url_path --path_url=path_to_normalize
Arguments:
-p,--path_url: URL path to normalize before using it
Examples:
url_path=$(ynh_normalize_url_path $url_path)
ynh_normalize_url_path example # -> /example
ynh_normalize_url_path /example # -> /example
ynh_normalize_url_path /example/ # -> /example
ynh_normalize_url_path / # -> /
Details:
Handle the slash at the beginning of path and its absence at ending
Return a normalized url path
Requires YunoHost version 2.6.4 or higher.
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
Example: port=$(ynh_find_port --port=8080)
Details:
Requires YunoHost version 2.6.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.
nodejs
export
N_PREFIX is the directory of n, it needs to be loaded as a environment variable.
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.
2 variables are available:
- $nodejs_path: The absolute path of node for the chosen version.
- $nodejs_version: Just the version number of node for this app. Stored as 'nodejs_version' in settings.yml.
And 2 alias stored in variables:
- $nodejs_use_version: An old variable, not used anymore. Keep here to not break old apps
NB: $PATH will contain the path to node, it has to be propagated to any other shell which needs to use it.
That's means it has to be added to any systemd script.
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
If possible, prefer to use major version number (e.g. 8 instead of 8.10.0).
The crontab will handle the update of minor versions when needed.
Arguments:
-n,--nodejs_version: Version of node to install.
Details:
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
ynh_install_nodejs will install the version of node provided as argument by using n.
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.
package
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
Example: ynh_package_is_installed --package=yunohost && echo "ok"
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
Usage: ynh_package_update
Details:
Requires YunoHost version 2.2.4 or higher.
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 This helper can/should only be called once per app
Usage: ynh_install_app_dependencies dep [dep [...]]
You can give a choice between some package with this syntax : "dep1|dep2"
Example : ynh_install_app_dependencies dep1 dep2 "dep3|dep4|dep5"
This mean in the dependence tree : dep1 & dep2 & (dep3 | dep4 | dep5)
Arguments:
dep: the package name to install in dependence
Details:
Requires YunoHost version 2.6.4 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_die
Print a message to stderr and exit usage: ynh_die --message=MSG [--ret_code=RETCODE]
ynh_print_info
Display a message in the 'INFO' logging category
Usage: ynh_print_info --message="Some message"
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 command to execute
ynh_exec_err "command to execute | following command"
In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe.
If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.
Arguments:
command: command to execute
Details:
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 command to execute
ynh_exec_warn "command to execute | following command"
In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe.
If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.
Arguments:
command: command to execute
Details:
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 command to execute
ynh_exec_warn_less "command to execute | following command"
In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe.
If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.
Arguments:
command: command to execute
Details:
Requires YunoHost version 3.2.0 or higher.
ynh_exec_quiet
Execute a command and redirect stdout in /dev/null
Usage: ynh_exec_quiet command to execute
ynh_exec_quiet "command to execute | following command"
In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe.
If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.
Arguments:
command: command to execute
Details:
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_fully_quiet command to execute
ynh_exec_fully_quiet "command to execute | following command"
In case of use of pipes, you have to use double quotes. Otherwise, this helper will be executed with the first command, then be sent to the next pipe.
If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.
Arguments:
command: command to execute
Details:
Requires YunoHost version 3.2.0 or higher.
ynh_print_OFF
Remove any logs for all the following commands.
Usage: ynh_print_OFF
WARNING: You should be careful with this helper, and never forget to use ynh_print_ON as soon as possible to restore the logging.
Details:
Requires YunoHost version 3.2.0 or higher.
ynh_print_ON
Restore the logging after ynh_print_OFF
increment_progression=0
Print a message as INFO and show progression during 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.-l,--last=: Use for the last call of the helper, to fill te progression bar.
Details:
Requires YunoHost version 3.?.? or higher.
psql
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
Example: ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;" example: ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql
Details:
Requires YunoHost version 3.?.? 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.?.? 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.?.? 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.?.? or higher.
ynh_psql_user_exists
Check if a psql user exists
Usage: ynh_psql_user_exists --user=user
Arguments:
-u,--user: the user for which to check existence
ynh_psql_database_exists
Check if a psql database exists
Usage: ynh_psql_database_exists --database=database
Arguments:
-d,--database: the database for which to check existence
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 given, 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.
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
ynh_psql_test_if_first_run
Create a master password and set up global settings Please always call this script in install and restore scripts
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.
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)
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.
system
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_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_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 [-n service_name] [-a action] [ [-l "line to match"] [-p log_path] [-t timeout] [-e length] ]
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.
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.-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 : 20
ynh_clean_check_starting
Clean temporary process and file used by ynh_check_starting (usually used in ynh_clean_setup scripts)
ynh_read_manifest
Read the value of a key in a ynh manifest file
Usage: ynh_read_manifest manifest key
Arguments:
-m,--manifest=: Path of the manifest to read-k,--key=: Name of the key to find
Details:
Requires YunoHost version 3.?.? or higher.
ynh_app_upstream_version
Read the upstream version from the manifest The version number in the manifest is defined by ~ynh For example : 4.3-2~ynh3 This include the number before ~ynh In the last example it return 4.3-2
Usage: ynh_app_upstream_version [-m manifest]
Arguments:
-m,--manifest=: Path of the manifest to read
Details:
Requires YunoHost version 3.?.? or higher.
ynh_app_package_version
Read package version from the manifest The version number in the manifest is defined by ~ynh For example : 4.3-2~ynh3 This include the number after ~ynh In the last example it return 3
Usage: ynh_app_package_version [-m manifest]
Arguments:
-m,--manifest=: Path of the manifest to read
Details:
Requires YunoHost version 3.?.? or higher.
ynh_check_app_version_changed
Checks the app version to upgrade with the existing app version and returns: - UPGRADE_APP if the upstream app version has changed - UPGRADE_PACKAGE if only the YunoHost package has changed
Usage: ynh_check_app_version_changed
Details:
It stops the current script without error if the package is up-to-date
This helper should be used to avoid an upgrade of an app, or the upstream part
of it, when it's not needed
To 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 MyApp
Requires YunoHost version 3.?.? 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
Example: ynh_user_exists 'toto' || exit 1
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: string - the key's value
Example: mail=$(ynh_user_get_info 'toto' 'mail')
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_user_list
Get the list of YunoHost users
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.
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
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
ynh_system_user_create
Create a system user
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 shell
Examples:
-
Create a nextcloud user with no home directory and /usr/sbin/nologin login shell (hence no login capability)
ynh_system_user_create --username=nextcloud
Create a discourse user using /var/www/discourse as home directory and the default login shell
ynh_system_user_create --username=discourse --home_dir=/var/www/discourse --use_shell
Details:
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.
utils
ynh_get_plain_key
Extract a key from a plain command output
Usage: ynh_get_plain_key key [subkey [subsubkey ...]]
Returns: string - the key's value
Example: yunohost user info tata --output-as plain | ynh_get_plain_key mail
Details:
Requires YunoHost version 2.2.4 or higher.
ynh_restore_upgradebackup
Restore a previous backup if the upgrade process failed
Usage: ynh_backup_before_upgrade
ynh_clean_setup () {
ynh_restore_upgradebackup
}
ynh_abort_if_errors
Details:
Requires YunoHost version 2.7.2 or higher.
ynh_backup_before_upgrade
Make a backup in case of failed upgrade
Usage: ynh_backup_before_upgrade
ynh_clean_setup () {
ynh_restore_upgradebackup
}
ynh_abort_if_errors
Details:
Requires YunoHost version 2.7.2 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]
Arguments:
-d,--dest_dir: Directory where to setup sources-s,--source_id: Name of the app, if the package contains more than one app
Details:
The file conf/app.src need to contains:
SOURCE_URL=Address to download the app archive
SOURCE_SUM=Control sum
# (Optional) Program to check the integrity (sha256sum, md5sum...)
# default: sha256
SOURCE_SUM_PRG=sha256
# (Optional) Archive format
# default: tar.gz
SOURCE_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: true
SOURCE_EXTRACT=(true|false)
Details:
This helper downloads sources from SOURCE_URL if there is no local source
archive in /opt/yunohost-apps-src/APP_ID/SOURCE_FILENAME
Next, 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 the
SOURCE_IN_SUBDIR is true, the first level directory of the archive will be
removed.
If SOURCE_IN_SUBDIR is a numeric value, 2 for example, the 2 first level
directories will be removed
Finally, patches named sources/patches/${src_id}-*.patch and extra files in
sources/extra_files/$src_id will be applied to dest_dir
Requires YunoHost version 2.6.4 or higher.
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:
$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_render_template
Render templates with Jinja2
Usage: ynh_render_template some_template output_path
Arguments:
some_template: Template file to be renderedoutput_path: The path where the output will be redirected to
Details:
Attention : Variables should be exported before calling this helper to be
accessible inside templates.
Generated by this script on 2019-04-08 18:53:09.449596 (version 3.5.1.1)