App helpers

backend

ynh_use_logrotate
Use logrotate to manage the logfile

Usage: ynh_use_logrotate [logfile] [--non-append|--append] [specific_user/specific_group]

Arguments:

  • logfile : absolute path of logfile
  • --non-append : (Option) Replace the config file instead of appending this new config.
  • specific_user : run logrotate as the specified user and group. If not specified logrotate is runned as root.

Details:

If no argument provided, a standard directory will be use. /var/log/${app}
You can provide a path with the directory only or with the logfile.
/parentdir/logdir
/parentdir/logdir/logfile.log

It's possible to use this helper several times, each config will be added to the same logrotate config file.
Unless you use the option --non-append

Dude, show me the code !

ynh_remove_logrotate
Remove the app's logrotate config.

Usage: ynh_remove_logrotate

Dude, show me the code !

ynh_add_systemd_config
Create a dedicated systemd config

Usage: ynh_add_systemd_config [service] [template]

Arguments:

  • service : Service name (optionnal, $app by default)
  • 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

Dude, show me the code !

ynh_remove_systemd_config
Remove the dedicated systemd config

Usage: ynh_remove_systemd_config [service]

Arguments:

  • service : Service name (optionnal, $app by default)

Dude, show me the code !

ynh_add_nginx_config
Create a dedicated nginx config

Usage: ynh_add_nginx_config "list of others variables to replace"

Arguments:

  • list : ['others', 'variables', 'to', 'replace', 'separeted', 'by', 'a', 'space']

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

Dude, show me the code !

ynh_remove_nginx_config
Remove the dedicated nginx config

Usage: ynh_remove_nginx_config

Dude, show me the code !

ynh_add_fpm_config
Create a dedicated php-fpm config

Usage: ynh_add_fpm_config

Dude, show me the code !

ynh_remove_fpm_config
Remove the dedicated php-fpm config

Usage: ynh_remove_fpm_config

Dude, show me the code !

filesystem

ynh_backup
Add a file or a directory to the list of paths to backup

Usage: ynh_backup src [dest [is_big [arg]]] the backup dir. backup dir

Arguments:

  • src : file or directory to bind or symlink or copy. it shouldn't be in
  • dest : destination file or directory inside the
  • is_big : 1 to indicate data are big (mail, video, image ...)
  • arg : Deprecated arg

Example: # Wordpress app context

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.

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"

Dude, show me the code !

ynh_restore
Restore all files linked to the restore hook or to the restore app script

Usage: ynh_restore

Dude, show me the code !

ynh_restore_file
Restore a file or a directory

Usage: ynh_restore_file ORIGIN_PATH [ DEST_PATH ] to be backuped or relative path to $YNH_CWD where it is located in the backup archive 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

Arguments:

  • ORIGIN_PATH : Path where was located the file or the directory before
  • DEST_PATH : Path where restore the file or the dir, if unspecified,

Example: ynh_restore_file "/etc/nginx/conf.d/$domain.d/$app.conf" # 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 a correspondance in the csv (eg: conf/nginx.conf) and restore it into # /etc/nginx/conf.d/$domain.d/$app.conf

Details:

Use the registered path in backup_list by ynh_backup to restore the file at
the good 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.

# DON'T GIVE THE ARCHIVE PATH:
ynh_restore_file "conf/nginx.conf"

Dude, show me the code !

ynh_store_file_checksum
Calculate and store a file checksum into the app settings

Usage: ynh_store_file_checksum file

Arguments:

  • file : The file on which the checksum will performed, then stored.

Details:

$app should be defined when calling this helper

Dude, show me the code !

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

Arguments:

  • file : The file on which the checksum test will be perfomed.

Details:

$app should be defined when calling this helper

| ret: Return the name a the backup file, or nothing

Dude, show me the code !

ynh_secure_remove
Remove a file or a directory securely

Usage: ynh_secure_remove path_to_remove

Arguments:

  • path_to_remove : File or directory to remove

Dude, show me the code !

ip

ynh_validate_ip
Validate an IP address

Usage: ynh_validate_ip [family] [ip_address]

Returns: 0 for valid ip addresses, 1 otherwise

Example: ynh_validate_ip 4 111.222.333.444

Dude, show me the code !

ynh_validate_ip4
Validate an IPv4 address

Usage: ynh_validate_ip4

Returns: 0 for valid ipv4 addresses, 1 otherwise

Example: ynh_validate_ip4 111.222.333.444

Dude, show me the code !

ynh_validate_ip6
Validate an IPv6 address

Usage: ynh_validate_ip6

Returns: 0 for valid ipv6 addresses, 1 otherwise

Example: ynh_validate_ip6 2000:dead:beef::1

Dude, show me the code !

mysql

ynh_mysql_connect_as
Open a connection as a user

Usage: ynh_mysql_connect_as user pwd [db]

Arguments:

  • user : the user name to connect as
  • pwd : the user password
  • db : the database to connect to

Example: ynh_mysql_connect_as 'user' 'pass' <<< "UPDATE ...;" example: ynh_mysql_connect_as 'user' 'pass' < /path/to/file.sql

Dude, show me the code !

ynh_mysql_execute_as_root
Execute a command as root user

Usage: ynh_mysql_execute_as_root sql [db]

Arguments:

  • sql : the SQL command to execute
  • db : the database to connect to

Dude, show me the code !

ynh_mysql_execute_file_as_root
Execute a command from a file as root user

Usage: ynh_mysql_execute_file_as_root file [db]

Arguments:

  • file : the file containing SQL commands
  • db : the database to connect to

Dude, show me the code !

ynh_mysql_dump_db
Dump a database

Usage: ynh_mysql_dump_db db

Arguments:

  • db : the database name to dump

Returns: the mysqldump output

Example: ynh_mysql_dump_db 'roundcube' > ./dump.sql

Dude, show me the code !

ynh_mysql_user_exists
Check if a mysql user exists

Usage: ynh_mysql_user_exists user

Arguments:

  • user : the user for which to check existence

Dude, show me the code !

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 user name [pwd]

Arguments:

  • user : Owner of the database
  • name : Name of the database
  • 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 "mysqlpwd" into the app settings.

Dude, show me the code !

ynh_mysql_remove_db
Remove a database if it exists, and the associated user

Usage: ynh_mysql_remove_db user name

Arguments:

  • user : Owner of the database
  • name : Name of the database

Dude, show me the code !

ynh_sanitize_dbid
Sanitize a string intended to be the name of a database (More specifically : replace - and . by _)

Usage: ynh_sanitize_dbid name

Arguments:

  • name : name to correct/sanitize

Returns: the corrected name

Example: dbname=$(ynh_sanitize_dbid $app)

Dude, show me the code !

network

ynh_normalize_url_path
Normalize the url path syntax Handle the slash at the beginning of path and its absence at ending Return a normalized url path

Usage: ynh_normalize_url_path path_to_normalize

Arguments:

  • url_path_to_normalize : URL path to normalize before using it

Example: 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 / -> /

Dude, show me the code !

ynh_find_port
Find a free port and return it

Usage: ynh_find_port begin_port

Arguments:

  • begin_port : port to start to search

Example: port=$(ynh_find_port 8080)

Dude, show me the code !

ynh_webpath_available
Check availability of a web path

Usage: ynh_webpath_available domain path

Arguments:

  • domain : the domain/host of the url
  • path : the web path to check the availability of

Example: ynh_webpath_available some.domain.tld /coffee

Dude, show me the code !

ynh_webpath_register
Register/book a web path for an app

Usage: ynh_webpath_register app domain path

Arguments:

  • app : the app for which the domain should be registered
  • domain : the domain/host of the web path
  • path : the web path to be registered

Example: ynh_webpath_register wordpress some.domain.tld /coffee

Dude, show me the code !

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.

Dude, show me the code !

ynh_install_nodejs
Install a specific version of nodejs

Usage: ynh_install_nodejs [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:

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

Dude, show me the code !

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.

Dude, show me the code !

package

ynh_package_is_installed
Check either a package is installed or not

Usage: ynh_package_is_installed name

Arguments:

  • name : the package name to check

Example: ynh_package_is_installed 'yunohost' && echo "ok"

Dude, show me the code !

ynh_package_version
Get the version of an installed package

Usage: ynh_package_version name

Arguments:

  • name : the package name to get version

Returns: the version or an empty string

Example: version=$(ynh_package_version 'yunohost')

Dude, show me the code !

ynh_package_update
Update package index files

Usage: ynh_package_update

Dude, show me the code !

ynh_package_install
Install package(s)

Usage: ynh_package_install name [name [...]]

Arguments:

  • name : the package name to install

Dude, show me the code !

ynh_package_remove
Remove package(s)

Usage: ynh_package_remove name [name [...]]

Arguments:

  • name : the package name to remove

Dude, show me the code !

ynh_package_autoremove
Remove package(s) and their uneeded dependencies

Usage: ynh_package_autoremove name [name [...]]

Arguments:

  • name : the package name to remove

Dude, show me the code !

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

Dude, show me the code !

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

Dude, show me the code !

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.

Dude, show me the code !

print

ynh_die
Print a message to stderr and exit usage: ynh_die MSG [RETCODE]
ynh_info
Display a message in the 'INFO' logging category

Usage: ynh_info "Some message"

Dude, show me the code !

psql

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

Usage: ynh_psql_test_if_first_run

Dude, show me the code !

ynh_psql_connect_as
Open a connection as a user

Usage: ynh_psql_connect_as user pwd [db]

Arguments:

  • user : the user name to connect as
  • pwd : the user password
  • db : the database to connect to

Example: ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;" example: ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql

Dude, show me the code !

ynh_psql_execute_as_root
# Execute a command as root user

Usage: ynh_psql_execute_as_root sql [db]

Arguments:

  • sql : the SQL command to execute

Dude, show me the code !

ynh_psql_execute_file_as_root
Execute a command from a file as root user

Usage: ynh_psql_execute_file_as_root file [db]

Arguments:

  • file : the file containing SQL commands
  • db : the database to connect to

Dude, show me the code !

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 user name [pwd]

Arguments:

  • user : Owner of the database
  • name : Name of the database
  • 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.

Dude, show me the code !

ynh_psql_create_db
Create a database and grant privilegies to a user

Usage: ynh_psql_create_db db [user [pwd]]

Arguments:

  • db : the database name to create
  • user : the user to grant privilegies
  • pwd : the user password

Dude, show me the code !

ynh_psql_remove_db
Drop a database

Usage: ynh_psql_drop_db db

Arguments:

  • db : the database name to drop
  • user : the user to drop

Dude, show me the code !

ynh_psql_dump_db
Dump a database

Usage: ynh_psql_dump_db db

Arguments:

  • db : the database name to dump

Returns: the psqldump output

Example: ynh_psql_dump_db 'roundcube' > ./dump.sql

Dude, show me the code !

ynh_psql_create_user
Create a user

Usage: ynh_psql_create_user user pwd [host]

Arguments:

  • user : the user name to create

Dude, show me the code !

ynh_psql_drop_user
Drop a user

Usage: ynh_psql_drop_user user

Arguments:

  • user : the user name to drop

Dude, show me the code !

setting

ynh_app_setting_get
Get an application setting

Usage: ynh_app_setting_get app key

Arguments:

  • app : the application id
  • key : the setting to get

Dude, show me the code !

ynh_app_setting_set
Set an application setting

Usage: ynh_app_setting_set app key value

Arguments:

  • app : the application id
  • key : the setting name to set
  • value : the setting value to set

Dude, show me the code !

ynh_app_setting_delete
Delete an application setting

Usage: ynh_app_setting_delete app key

Arguments:

  • app : the application id
  • key : the setting to delete

Dude, show me the code !

string

ynh_string_random
Generate a random string

Usage: ynh_string_random [length]

Arguments:

  • length : the string length to generate (default: 24)

Example: pwd=$(ynh_string_random 8)

Dude, show me the code !

ynh_replace_string
Substitute/replace a string (or expression) by another in a file

Usage: ynh_replace_string match_string replace_string target_file

Arguments:

  • match_string : String to be searched and replaced in the file
  • replace_string : String that will replace matches
  • 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)

Dude, show me the code !

ynh_replace_special_string
Substitute/replace a special string by another in a file

Usage: ynh_replace_special_string match_string replace_string target_file

Arguments:

  • match_string : String to be searched and replaced in the file
  • replace_string : String that will replace matches
  • 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.

Dude, show me the code !

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.

Dude, show me the code !

ynh_get_debian_release
Fetch the Debian release codename

Usage: ynh_get_debian_release

Returns: The Debian release codename (i.e. jessie, stretch, ...)

Dude, show me the code !

user

ynh_user_exists
Check if a YunoHost user exists

Usage: ynh_user_exists username

Arguments:

  • username : the username to check

Example: ynh_user_exists 'toto' || exit 1

Dude, show me the code !

ynh_user_get_info
Retrieve a YunoHost user information

Usage: ynh_user_get_info username key

Arguments:

  • username : the username to retrieve info from
  • key : the key to retrieve

Returns: string - the key's value

Example: mail=$(ynh_user_get_info 'toto' 'mail')

Dude, show me the code !

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

Dude, show me the code !

ynh_system_user_exists
Check if a user exists on the system

Usage: ynh_system_user_exists username

Arguments:

  • username : the username to check

Dude, show me the code !

ynh_system_user_create
Create a system user

Usage: ynh_system_user_create user_name [home_dir]

Arguments:

  • user_name : Name of the system user that will be create
  • 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

Dude, show me the code !

ynh_system_user_delete
Delete a system user

Usage: ynh_system_user_delete user_name

Arguments:

  • user_name : Name of the system user that will be create

Dude, show me the code !

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

Dude, show me the code !

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

Dude, show me the code !

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

Dude, show me the code !

ynh_setup_source
Download, check integrity, uncompress and patch the source from app.src

Usage: ynh_setup_source dest_dir [source_id]

Arguments:

  • dest_dir : Directory where to setup sources
  • 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
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.

Finally, patches named sources/patches/${src_id}-*.patch and extra files in
sources/extra_files/$src_id will be applied to dest_dir

Dude, show me the code !

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 sent
  • key1=value1 : (Optionnal) POST key and corresponding value
  • key2=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?))

Dude, show me the code !

ynh_render_template
Render templates with Jinja2

Usage: ynh_render_template some_template output_path

Arguments:

  • some_template : Template file to be rendered
  • output_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.

Dude, show me the code !