From 306a83dcd02bdcf508f63964d54117336ba99e92 Mon Sep 17 00:00:00 2001 From: Kay0u Date: Sun, 7 Feb 2021 15:50:29 +0100 Subject: [PATCH] Update packaging_apps_helpers --- .../11.helpers/packaging_apps_helpers.md | 6487 ++++++----------- 1 file changed, 2135 insertions(+), 4352 deletions(-) diff --git a/pages/02.contribute/04.packaging_apps/11.helpers/packaging_apps_helpers.md b/pages/02.contribute/04.packaging_apps/11.helpers/packaging_apps_helpers.md index 803a5af7..9ab374f1 100644 --- a/pages/02.contribute/04.packaging_apps/11.helpers/packaging_apps_helpers.md +++ b/pages/02.contribute/04.packaging_apps/11.helpers/packaging_apps_helpers.md @@ -7,5575 +7,3358 @@ routes: default: '/packaging_apps_helpers' --- - +Doc auto-generated by [this script](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/doc/generate_helper_doc.py) on 02/07/2021 (Yunohost version 4.1.7) -

App helpers

-

Doc auto-generated by this script on 02/03/2021 (Yunohost version 4.1.7.1)

+### APT +**ynh_package_is_installed** +[details summary="Check either a package is installed or not" class="helper-card-subtitle text-muted"] +

- -

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

- - - -

- Example: ynh_package_is_installed --package=yunohost && echo "ok" -

- - - -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

- -

- Dude, show me the code ! -

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

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - -
-
-
-
ynh_package_update
-
Update package index files
-
-
-
-

- - Usage: ynh_package_update - -

- - - - - -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

- -

- Dude, show me the code ! -

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

-

-

- -

- Dude, show me the code ! -

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

-

-

- -

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

- - - - - -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

- -

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

- - - - - -

- Details: -

- Requires YunoHost version 2.7.2 or higher.

-

-

+**Usage**: `ynh_package_is_installed --package=name` -

- Dude, show me the code ! -

-
-
- -
- - - -
-
-
-
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. Writing "dep3|dep4|dep5" can be used to specify alternatives. For example : dep1 dep2 "dep3|dep4|dep5" will require to install dep1 and dep 2 and (dep3 or dep4 or dep5).
    • - - -
-

- - - - - -

- Details: -

- This helper can/should only be called once per app

example : ynh_install_app_dependencies dep1 dep2 "dep3|dep4|dep5"

Requires YunoHost version 2.6.4 or higher.

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - -
-
-
-
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.
    • - - - -
  • -r, --replace : Replace dependencies instead of adding to existing ones.
    • - - -
-

- - - - - -

- Details: -

- Requires YunoHost version 3.8.1 or higher.

-

-

- -

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

Requires YunoHost version 2.6.4 or higher.

-

-

- -

- Dude, show me the code ! -

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

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - - -

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.
    • - - - -
  • arg : Deprecated arg
    • - - -
-

- - - - - -

- Details: -

- This helper can be used both in a system backup hook, and in an app backup script

Details: ynh_backup writes SRC and the relative DEST into a CSV file. And it
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"

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

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - -
-
-
-
ynh_restore
-
Restore all files that were previously backuped in a core backup script or app backup script
-
-
-
-

- - Usage: ynh_restore - -

- - - - - -

- Details: -

- Requires YunoHost version 2.6.4 or higher.

-

-

- -

- Dude, show me the code ! -

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

    +**Arguments**: - ynh_restore_file "/etc/nginx/conf.d/$domain.d/$app.conf" +- `-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.

    + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/apt#L56) +[/details] +---------------- + +**ynh_package_version** +[details summary="Get the version of an installed package" class="helper-card-subtitle text-muted"] +

    + +**Usage**: `ynh_package_version --package=name` + + +**Arguments**: - You can also use relative paths: +- `-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.

    + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/apt#L78) +[/details] +---------------- + +**ynh_package_update** +[details summary="Update package index files" class="helper-card-subtitle text-muted"] +

    + +**Usage**: `ynh_package_update` + + + + + + +**Details**: +Requires YunoHost version 2.2.4 or higher.

    + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/apt#L111) +[/details] +---------------- + +**ynh_package_install** +[details summary="Install package(s)" class="helper-card-subtitle text-muted"] +

    + +**Usage**: `ynh_package_install name [name [...]]` + + +**Arguments**: - ynh_restore_file "conf/nginx.conf" +- `name`: the package name to install -
    -
-

-

- 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.
Requires YunoHost version 3.5.0 or higher for the argument --not_mandatory

-

-

-

- Dude, show me the code ! -

+ + -
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/apt#L121) +[/details] +---------------- +**ynh_package_remove** +[details summary="Remove package(s)" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_package_remove name [name [...]]` + -
-
-
-
ynh_store_file_checksum
-
Calculate and store a file checksum into the app settings
-
-
-
-

+**Arguments**: - Usage: ynh_store_file_checksum --file=file + +- `name`: the package name to remove + -

- -

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

-

-

- -

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/apt#L132) +[/details] +---------------- +**ynh_package_autoremove** +[details summary="Remove package(s) and their uneeded dependencies" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_package_autoremove name [name [...]]` + -
-
-
-
ynh_backup_if_checksum_is_different
-
Verify the checksum and backup the file if it's different
-
-
-
-

+**Arguments**: - Usage: ynh_backup_if_checksum_is_different --file=file + +- `name`: the package name to remove + -

- -

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

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/apt#L142) +[/details] +---------------- +**ynh_package_autopurge** +[details summary="Purge package(s) and their uneeded dependencies" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_package_autopurge name [name [...]]` + -
-
-
-
ynh_delete_file_checksum
-
Delete a file checksum from the app settings
-
-
-
-

+**Arguments**: - Usage: ynh_delete_file_checksum --file=file + +- `name`: the package name to autoremove and purge + -

- -

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

-

-

- -

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.7.2 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/apt#L152) +[/details] +---------------- +**ynh_install_app_dependencies** +[details summary="Define and install dependencies with a equivs control file" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_install_app_dependencies dep [dep [...]]` + -
-
-
-
ynh_backup_before_upgrade
-
Make a backup in case of failed upgrade
-
-
-
-

+**Arguments**: - Usage: ynh_backup_before_upgrade + +- `dep`: the package name to install in dependence. Writing "dep3|dep4|dep5" can be used to specify alternatives. For example : dep1 dep2 "dep3|dep4|dep5" will require to install dep1 and dep 2 and (dep3 or dep4 or dep5). + + + + + + + + +**Details**: +This helper can/should only be called once per app

example : ynh\_install\_app\_dependencies dep1 dep2 "dep3|dep4|dep5"

Requires YunoHost version 2.6.4 or higher.

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/apt#L222) +[/details] +---------------- + +**ynh_add_app_dependencies** +[details summary="Add dependencies to install with ynh_install_app_dependencies" class="helper-card-subtitle text-muted"] +

+ +**Usage**: `ynh_add_app_dependencies --package=phpversion [--replace]` + + +**Arguments**: + + +- `-p`, `--package=`: Packages to add as dependencies for the app. + + + +- `-r`, `--replace`: Replace dependencies instead of adding to existing ones. + + + + + + + + +**Details**: +Requires YunoHost version 3.8.1 or higher.

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/apt#L295) +[/details] +---------------- + +**ynh_remove_app_dependencies** +[details summary="Remove fake package and its dependencies" class="helper-card-subtitle text-muted"] +

+ +**Usage**: `ynh_remove_app_dependencies` + + + + + + +**Details**: +Dependencies will removed only if no other package need them.

Requires YunoHost version 2.6.4 or higher.

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/apt#L327) +[/details] +---------------- + +**ynh_install_extra_app_dependencies** +[details summary="Install packages from an extra repository properly." class="helper-card-subtitle text-muted"] +

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

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/apt#L341) +[/details] +---------------- + + +### BACKUP + +**ynh_backup** +[details summary="Add a file or a directory to the list of paths to backup" class="helper-card-subtitle text-muted"] +

+ +**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**: +This helper can be used both in a system backup hook, and in an app backup script

Details: ynh\_backup writes SRC and the relative DEST into a CSV file. And it
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"

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

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/backup#L63) +[/details] +---------------- + +**ynh_restore** +[details summary="Restore all files that were previously backuped in a core backup script or app backup script" class="helper-card-subtitle text-muted"] +

+ +**Usage**: `ynh_restore` + + + + + + +**Details**: +Requires YunoHost version 2.6.4 or higher.

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/backup#L186) +[/details] +---------------- + +**ynh_restore_file** +[details summary="Restore a file or a directory" class="helper-card-subtitle text-muted"] +

+ +**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.
Requires YunoHost version 3.5.0 or higher for the argument --not\_mandatory

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/backup#L247) +[/details] +---------------- + +**ynh_store_file_checksum** +[details summary="Calculate and store a file checksum into the app settings" class="helper-card-subtitle text-muted"] +

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

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/backup#L325) +[/details] +---------------- + +**ynh_backup_if_checksum_is_different** +[details summary="Verify the checksum and backup the file if it's different" class="helper-card-subtitle text-muted"] +

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

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/backup#L357) +[/details] +---------------- + +**ynh_delete_file_checksum** +[details summary="Delete a file checksum from the app settings" class="helper-card-subtitle text-muted"] +

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

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/backup#L390) +[/details] +---------------- + +**ynh_backup_before_upgrade** +[details summary="Make a backup in case of failed upgrade" class="helper-card-subtitle text-muted"] +

+ +**Usage**: `ynh_backup_before_upgrade ynh_clean_setup () { ynh_restore_upgradebackup } - ynh_abort_if_errors - -

+ ynh_abort_if_errors` -

- Details: -

- Requires YunoHost version 2.7.2 or higher.

-

-

- -

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.7.2 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/backup#L412) +[/details] +---------------- +**ynh_restore_upgradebackup** +[details summary="Restore a previous backup if the upgrade process failed" class="helper-card-subtitle text-muted"] +

- -
-
-
-
ynh_restore_upgradebackup
-
Restore a previous backup if the upgrade process failed
-
-
-
-

- - Usage: ynh_backup_before_upgrade +**Usage**: `ynh_backup_before_upgrade ynh_clean_setup () { ynh_restore_upgradebackup } - ynh_abort_if_errors - -

+ ynh_abort_if_errors` -

- Details: -

- Requires YunoHost version 2.7.2 or higher.

-

-

+ +**Details**: +Requires YunoHost version 2.7.2 or higher.

-

- Dude, show me the code ! -

-
-
- -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/backup#L461) +[/details] +---------------- +### FAIL2BAN +**ynh_add_fail2ban_config** +[details summary="Create a dedicated fail2ban config (jail and filter conf files)" class="helper-card-subtitle text-muted"] +

-

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] +**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 ...' - -

+| 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
    • - - + +**Arguments**: + -
  • -m, --max_retry= : Maximum number of retries allowed before banning IP address - default: 3
    • +- `-l`, `--logpath=`: Log file to be checked by fail2ban + +- `-r`, `--failregex=`: Failregex to be looked for by fail2ban -
  • -p, --ports= : Ports blocked for a banned IP address - default: http,https
    • + +- `-m`, `--max_retry=`: Maximum number of retries allowed before banning IP address - default: 3 + -
  • -t, --use_template : Use this helper in template mode
    • +- `-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
    • + +- `-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.5.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
- -
+**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.5.0 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/fail2ban#L65) +[/details] +---------------- +**ynh_remove_fail2ban_config** +[details summary="Remove the dedicated fail2ban config (jail and filter conf files)" class="helper-card-subtitle text-muted"] +

-
-
-
-
ynh_remove_fail2ban_config
-
Remove the dedicated fail2ban config (jail and filter conf files)
-
-
-
-

- - Usage: ynh_remove_fail2ban_config - -

- +**Usage**: `ynh_remove_fail2ban_config` -

- Details: -

- Requires YunoHost version 3.5.0 or higher.

-

-

-

- Dude, show me the code ! -

- -
-
- -
- - +**Details**: +Requires YunoHost version 3.5.0 or higher.

+ -

getopts

+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/fail2ban#L150) +[/details] +---------------- +### GETOPTS -

hardware

+### HARDWARE +**ynh_get_ram** +[details summary="Get the total or free amount of RAM+swap on the system" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_get_ram [--free|--total] [--ignore_swap|--only_swap]` + -
-
-
-
ynh_get_ram
-
Get the total or free amount of RAM+swap on the system
-
-
-
-

+**Arguments**: - Usage: ynh_get_ram [--free|--total] [--ignore_swap|--only_swap] - -

- -

- Arguments: -

    - - -
  • -f, --free : Count free RAM+swap
    • - - - -
  • -t, --total : Count total RAM+swap
    • +- `-f`, `--free`: Count free RAM+swap + -
  • -s, --ignore_swap : Ignore swap, consider only real RAM
    • +- `-t`, `--total`: Count total RAM+swap + +- `-s`, `--ignore_swap`: Ignore swap, consider only real RAM -
  • -o, --only_swap : Ignore real RAM, consider only swap
    • + +- `-o`, `--only_swap`: Ignore real RAM, consider only swap -
-

- + -

- Returns: the amount of free ram -

+ +**Returns**: the amount of free ram -

- Details: -

- Requires YunoHost version 3.8.1 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 3.8.1 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/hardware#L13) +[/details] +---------------- +**ynh_require_ram** +[details summary="Return 0 or 1 depending if the system has a given amount of RAM+swap free or total" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_require_ram --required=RAM required in Mb [--free|--total] [--ignore_swap|--only_swap] +| exit: Return 1 if the ram is under the requirement, 0 otherwise.` + -
-
-
-
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 required in Mb [--free|--total] [--ignore_swap|--only_swap] -| exit: Return 1 if the ram is under the requirement, 0 otherwise. +**Arguments**: -

- -

- Arguments: -

    - - -
  • -r, --required= : The amount to require, in Mb
    • - - - -
  • -f, --free : Count free RAM+swap
    • +- `-r`, `--required=`: The amount to require, in Mb + -
  • -t, --total : Count total RAM+swap
    • - +- `-f`, `--free`: Count free RAM+swap + -
  • -s, --ignore_swap : Ignore swap, consider only real RAM
    • +- `-t`, `--total`: Count total RAM+swap + +- `-s`, `--ignore_swap`: Ignore swap, consider only real RAM -
  • -o, --only_swap : Ignore real RAM, consider only swap
    • + +- `-o`, `--only_swap`: Ignore real RAM, consider only swap -
-

- + -

- Details: -

- Requires YunoHost version 3.8.1 or higher.

-

-

-

- Dude, show me the code ! -

- -
-
- -
+**Details**: +Requires YunoHost version 3.8.1 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/hardware#L82) +[/details] +---------------- -

logging

+### LOGGING +**ynh_die** +[details summary="Print a message to stderr and exit" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_die --message=MSG [--ret_code=RETCODE]` + -
-
-
-
ynh_die
-
Print a message to stderr and exit
-
-
-
-

+**Arguments**: - Usage: ynh_die --message=MSG [--ret_code=RETCODE] - -

- -

- Arguments: -

    - - -
  • -m, --message= : Message to display
    • - +- `-m`, `--message=`: Message to display -
  • -c, --ret_code= : Exit code to exit with
    • + +- `-c`, `--ret_code=`: Exit code to exit with -
-

- + -

- Details: -

- Requires YunoHost version 2.4.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.4.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logging#L10) +[/details] +---------------- +**ynh_print_info** +[details summary="Display a message in the 'INFO' logging category" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_print_info --message="Some message"` + -
-
-
-
ynh_print_info
-
Display a message in the 'INFO' logging category
-
-
-
-

- - Usage: ynh_print_info --message="Some message" +**Arguments**: -

- -

- Arguments: -

    - - -
  • -m, --message= : Message to display
    • +- `-m`, `--message=`: Message to display -
-

- + -

- Details: -

- Requires YunoHost version 3.2.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 3.2.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logging#L30) +[/details] +---------------- +**ynh_print_warn** +[details summary="Print a warning on stderr" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_print_warn --message="Text to print"` + -
-
-
-
ynh_print_warn
-
Print a warning on stderr
-
-
-
-

- - Usage: ynh_print_warn --message="Text to print" +**Arguments**: -

- -

- Arguments: -

    - - -
  • -m, --message= : The text to print
    • +- `-m`, `--message=`: The text to print -
-

- + -

- Details: -

- Requires YunoHost version 3.2.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 3.2.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logging#L75) +[/details] +---------------- +**ynh_print_err** +[details summary="Print an error on stderr" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_print_err --message="Text to print"` + -
-
-
-
ynh_print_err
-
Print an error on stderr
-
-
-
-

- - Usage: ynh_print_err --message="Text to print" +**Arguments**: -

- -

- Arguments: -

    - - -
  • -m, --message= : The text to print
    • +- `-m`, `--message=`: The text to print -
-

- + -

- Details: -

- Requires YunoHost version 3.2.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 3.2.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logging#L92) +[/details] +---------------- +**ynh_exec_err** +[details summary="Execute a command and print the result as an error" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_exec_err your_command +ynh_exec_err "your_command | other_command"` + -
-
-
-
ynh_exec_err
-
Execute a command and print the result as an error
-
-
-
-

- - Usage: ynh_exec_err your_command -ynh_exec_err "your_command | other_command" +**Arguments**: -

- -

- Arguments: -

    - - -
  • command : command to execute
    • +- `command`: command to execute -
-

- + -

- Details: -

- When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.2.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.2.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logging#L114) +[/details] +---------------- +**ynh_exec_warn** +[details summary="Execute a command and print the result as a warning" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_exec_warn your_command +ynh_exec_warn "your_command | other_command"` + -
-
-
-
ynh_exec_warn
-
Execute a command and print the result as a warning
-
-
-
-

- - Usage: ynh_exec_warn your_command -ynh_exec_warn "your_command | other_command" +**Arguments**: -

- -

- Arguments: -

    +- `command`: command to execute -
  • command : command to execute
    • - - -
-

- + -

- Details: -

- When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.2.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.2.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logging#L129) +[/details] +---------------- +**ynh_exec_warn_less** +[details summary="Execute a command and force the result to be printed on stdout" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_exec_warn_less your_command +ynh_exec_warn_less "your_command | other_command"` + -
-
-
-
ynh_exec_warn_less
-
Execute a command and force the result to be printed on stdout
-
-
-
-

- - Usage: ynh_exec_warn_less your_command -ynh_exec_warn_less "your_command | other_command" +**Arguments**: -

- -

- Arguments: -

    +- `command`: command to execute -
  • command : command to execute
    • - - -
-

- + -

- Details: -

- When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.2.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.2.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logging#L144) +[/details] +---------------- +**ynh_exec_quiet** +[details summary="Execute a command and redirect stdout in /dev/null" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_exec_quiet your_command +ynh_exec_quiet "your_command | other_command"` + -
-
-
-
ynh_exec_quiet
-
Execute a command and redirect stdout in /dev/null
-
-
-
-

+**Arguments**: - Usage: ynh_exec_quiet your_command -ynh_exec_quiet "your_command | other_command" - -

- -

- Arguments: -

    +- `command`: command to execute -
  • command : command to execute
    • - - -
-

- + -

- Details: -

- When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.2.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.2.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logging#L159) +[/details] +---------------- +**ynh_exec_fully_quiet** +[details summary="Execute a command and redirect stdout and stderr in /dev/null" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_exec_fully_quiet your_command +ynh_exec_fully_quiet "your_command | other_command"` + -
-
-
-
ynh_exec_fully_quiet
-
Execute a command and redirect stdout and stderr in /dev/null
-
-
-
-

+**Arguments**: - Usage: ynh_exec_fully_quiet your_command -ynh_exec_fully_quiet "your_command | other_command" - -

- -

- Arguments: -

    - -
  • command : command to execute
    • +- `command`: command to execute - -
-

- + -

- Details: -

- When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.2.0 or higher.

-

-

-

- Dude, show me the code ! -

- -
-
-
+**Details**: +When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.2.0 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logging#L174) +[/details] +---------------- +**ynh_print_OFF** +[details summary="Remove any logs for all the following commands." class="helper-card-subtitle text-muted"] +

-
-
-
-
ynh_print_OFF
-
Remove any logs for all the following commands.
-
-
-
-

- - Usage: ynh_print_OFF - -

- +**Usage**: `ynh_print_OFF` -

- Details: -

- WARNING: You should be careful with this helper, and never forget to use ynh_print_ON as soon as possible to restore the logging.

Requires YunoHost version 3.2.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
- -
+**Details**: +WARNING: You should be careful with this helper, and never forget to use ynh\_print\_ON as soon as possible to restore the logging.

Requires YunoHost version 3.2.0 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logging#L185) +[/details] +---------------- +**ynh_print_ON** +[details summary="Restore the logging after ynh_print_OFF" class="helper-card-subtitle text-muted"] +

-
-
-
-
ynh_print_ON
-
Restore the logging after ynh_print_OFF
-
-
-
-

- - Usage: ynh_print_ON - -

- +**Usage**: `ynh_print_ON` -

- Details: -

- Requires YunoHost version 3.2.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 3.2.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logging#L194) +[/details] +---------------- +**ynh_script_progression** +[details summary="Print a progress bar showing the progression of an app script" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_script_progression --message=message [--weight=weight] [--time]` + -
-
-
-
ynh_script_progression
-
Print a progress bar showing the progression of an app script
-
-
-
-

- - Usage: ynh_script_progression --message=message [--weight=weight] [--time] +**Arguments**: -

- -

- 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.
    • +- `-m`, `--message=`: The text to print + -
  • -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.
    • +- `-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.
    • + +- `-l`, `--last`: Use for the last call of the helper, to fill the progression bar. -
-

- + -

- Details: -

- Requires YunoHost version 3.5.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
- -
+**Details**: +Requires YunoHost version 3.5.0 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logging#L222) +[/details] +---------------- +**ynh_return** +[details summary="Return data to the Yunohost core for later processing +(to be used by special hooks like app config panel and core diagnosis)" class="helper-card-subtitle text-muted"] +

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

- +**Usage**: `ynh_return somedata` -

- Details: -

- Requires YunoHost version 3.6.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 3.6.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logging#L307) +[/details] +---------------- +**ynh_debug** +[details summary="Debugger for app packagers" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_debug [--message=message] [--trace=1/0]` + -
-
-
-
ynh_debug
-
Debugger for app packagers
-
-
-
-

- - Usage: ynh_debug [--message=message] [--trace=1/0] +**Arguments**: -

- -

- Arguments: -

    - - -
  • -m, --message= : The text to print
    • +- `-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.
    • - +- `-t`, `--trace=`: Turn on or off the trace of the script. Usefull to trace nonly a small part of a script. -
-

- + -

- Details: -

- Requires YunoHost version 3.5.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 3.5.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logging#L318) +[/details] +---------------- +**ynh_debug_exec** +[details summary="Execute a command and print the result as debug" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_debug_exec your_command +ynh_debug_exec "your_command | other_command"` + -
-
-
-
ynh_debug_exec
-
Execute a command and print the result as debug
-
-
-
-

- - Usage: ynh_debug_exec your_command -ynh_debug_exec "your_command | other_command" +**Arguments**: -

- -

- Arguments: -

    - - -
  • command : command to execute
    • +- `command`: command to execute -
-

- + -

- Details: -

- When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.5.0 or higher.

-

-

-

- Dude, show me the code ! -

- -
-
- -
+**Details**: +When using pipes, double quotes are required - otherwise, this helper will run the first command, and the whole output will be sent through the next pipe.

If the command to execute uses double quotes, they have to be escaped or they will be interpreted and removed.

Requires YunoHost version 3.5.0 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logging#L375) +[/details] +---------------- -

logrotate

+### LOGROTATE +**ynh_use_logrotate** +[details summary="Use logrotate to manage the logfile" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_use_logrotate [--logfile=/log/file] [--nonappend] [--specific_user=user/group]` + -
-
-
-
ynh_use_logrotate
-
Use logrotate to manage the logfile
-
-
-
-

+**Arguments**: - Usage: ynh_use_logrotate [--logfile=/log/file] [--nonappend] [--specific_user=user/group] - -

- -

- Arguments: -

    +- `-l`, `--logfile=`: absolute path of logfile -
  • -l, --logfile= : absolute path of logfile
    • - - - -
  • -n, --nonappend : (optional) Replace the config file instead of appending this new config.
    • - + +- `-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.
    • + +- `-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.
Requires YunoHost version 3.2.0 or higher for the argument --specific_user

-

-

-

- Dude, show me the code ! -

- -
-
-
+**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.
Requires YunoHost version 3.2.0 or higher for the argument --specific\_user

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logrotate#L20) +[/details] +---------------- +**ynh_remove_logrotate** +[details summary="Remove the app's logrotate config." class="helper-card-subtitle text-muted"] +

-
-
-
-
ynh_remove_logrotate
-
Remove the app's logrotate config.
-
-
-
-

- - Usage: ynh_remove_logrotate - -

- +**Usage**: `ynh_remove_logrotate` -

- Details: -

- Requires YunoHost version 2.6.4 or higher.

-

-

-

- Dude, show me the code ! -

- -
-
- -
+**Details**: +Requires YunoHost version 2.6.4 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/logrotate#L108) +[/details] +---------------- -

mysql

+### MYSQL +**ynh_mysql_connect_as** +[details summary="Open a connection as a user" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_mysql_connect_as --user=user --password=password [--database=database]` + -
-
-
-
ynh_mysql_connect_as
-
Open a connection as a user
-
-
-
-

+**Arguments**: - Usage: ynh_mysql_connect_as --user=user --password=password [--database=database] - -

- -

- Arguments: -

    - - -
  • -u, --user= : the user name to connect as
    • - +- `-u`, `--user=`: the user name to connect as -
  • -p, --password= : the user password
    • - + +- `-p`, `--password=`: the user password -
  • -d, --database= : the database to connect to
    • + +- `-d`, `--database=`: the database to connect to -
-

- + -

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

+**Example**: `ynh_mysql_connect_as --user="user" --password="pass" <<< "UPDATE ...;" example: ynh_mysql_connect_as --user="user" --password="pass" < /path/to/file.sql` -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/mysql#L16) +[/details] +---------------- +**ynh_mysql_execute_as_root** +[details summary="Execute a command as root user" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_mysql_execute_as_root --sql=sql [--database=database]` + -
-
-
-
ynh_mysql_execute_as_root
-
Execute a command as root user
-
-
-
-

- - Usage: ynh_mysql_execute_as_root --sql=sql [--database=database] +**Arguments**: -

- -

- Arguments: -

    - - -
  • -s, --sql= : the SQL command to execute
    • +- `-s`, `--sql=`: the SQL command to execute + -
  • -d, --database= : the database to connect to
    • - +- `-d`, `--database=`: the database to connect to -
-

- + -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/mysql#L37) +[/details] +---------------- +**ynh_mysql_execute_file_as_root** +[details summary="Execute a command from a file as root user" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_mysql_execute_file_as_root --file=file [--database=database]` + -
-
-
-
ynh_mysql_execute_file_as_root
-
Execute a command from a file as root user
-
-
-
-

+**Arguments**: - Usage: ynh_mysql_execute_file_as_root --file=file [--database=database] - -

- -

- Arguments: -

    - - -
  • -f, --file= : the file containing SQL commands
    • - +- `-f`, `--file=`: the file containing SQL commands -
  • -d, --database= : the database to connect to
    • + +- `-d`, `--database=`: the database to connect to -
-

- + -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/mysql#L63) +[/details] +---------------- +**ynh_mysql_dump_db** +[details summary="Dump a database" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_mysql_dump_db --database=database` + -
-
-
-
ynh_mysql_dump_db
-
Dump a database
-
-
-
-

- - Usage: ynh_mysql_dump_db --database=database +**Arguments**: -

- -

- Arguments: -

    - - -
  • -d, --database= : the database name to dump
    • +- `-d`, `--database=`: the database name to dump -
-

- + -

- Returns: the mysqldump output -

+ +**Returns**: the mysqldump output -

- Example: ynh_mysql_dump_db --database=roundcube > ./dump.sql -

+**Example**: `ynh_mysql_dump_db --database=roundcube > ./dump.sql` -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/mysql#L135) +[/details] +---------------- +**ynh_mysql_user_exists** +[details summary="Check if a mysql user exists" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_mysql_user_exists --user=user +| exit: Return 1 if the user doesn't exist, 0 otherwise.` + -
-
-
-
ynh_mysql_user_exists
-
Check if a mysql user exists
-
-
-
-

+**Arguments**: - Usage: ynh_mysql_user_exists --user=user -| exit: Return 1 if the user doesn't exist, 0 otherwise. - -

- -

- Arguments: -

    - -
  • -u, --user= : the user for which to check existence
    • +- `-u`, `--user=`: the user for which to check existence - -
-

- + -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/mysql#L167) +[/details] +---------------- +**ynh_mysql_setup_db** +[details summary="Create a database, an user and its password. Then store the password in the app's config" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_mysql_setup_db --db_user=user --db_name=name [--db_pwd=pwd]` + -
-
-
-
ynh_mysql_setup_db
-
Create a database, an user and its password. Then store the password in the app's config
-
-
-
-

+**Arguments**: - Usage: ynh_mysql_setup_db --db_user=user --db_name=name [--db_pwd=pwd] - -

- -

- Arguments: -

    - - -
  • -u, --db_user= : Owner of the database
    • - +- `-u`, `--db_user=`: Owner of the database -
  • -n, --db_name= : Name 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
    • + +- `-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.

-

-

-

- Dude, show me the code ! -

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

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/mysql#L207) +[/details] +---------------- +**ynh_mysql_remove_db** +[details summary="Remove a database if it exists, and the associated user" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_mysql_remove_db --db_user=user --db_name=name` + -
-
-
-
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**: -

- -

- Arguments: -

    - - -
  • -u, --db_user= : Owner of the database
    • +- `-u`, `--db_user=`: Owner of the database + -
  • -n, --db_name= : Name of the database
    • - +- `-n`, `--db_name=`: Name of the database -
-

- + -

- Details: -

- Requires YunoHost version 2.6.4 or higher.

-

-

-

- Dude, show me the code ! -

- -
-
- -
+**Details**: +Requires YunoHost version 2.6.4 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/mysql#L232) +[/details] +---------------- -

network

+### NETWORK +**ynh_find_port** +[details summary="Find a free port and return it" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_find_port --port=begin_port` + -
-
-
-
ynh_find_port
-
Find a free port and return it
-
-
-
-

+**Arguments**: - Usage: ynh_find_port --port=begin_port - -

- -

- Arguments: -

    - -
  • -p, --port= : port to start to search
    • +- `-p`, `--port=`: port to start to search - -
-

- + -

- Returns: the port number -

+ +**Returns**: the port number -

- Example: port=$(ynh_find_port --port=8080) -

+**Example**: `port=$(ynh_find_port --port=8080)` -

- Details: -

- Requires YunoHost version 2.6.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.6.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/network#L12) +[/details] +---------------- +**ynh_port_available** +[details summary="Test if a port is available" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_find_port --port=XYZ +| exit: Return 1 if the port is already used by another process.` + -
-
-
-
ynh_port_available
-
Test if a port is available
-
-
-
-

- - Usage: ynh_find_port --port=XYZ -| exit: Return 1 if the port is already used by another process. +**Arguments**: -

- -

- Arguments: -

    +- `-p`, `--port=`: port to check -
  • -p, --port= : port to check
    • - - -
-

- + -

- Example: ynh_port_available --port=1234 || ynh_die "Port 1234 is needs to be available for this app" -

+**Example**: `ynh_port_available --port=1234 || ynh_die "Port 1234 is needs to be available for this app"` -

- Details: -

- Requires YunoHost version 3.8.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 3.8.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/network#L37) +[/details] +---------------- +**ynh_validate_ip4** +[details summary="Validate an IPv4 address" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_validate_ip4 --ip_address=ip_address` + -
-
-
-
ynh_validate_ip4
-
Validate an IPv4 address
-
-
-
-

+**Arguments**: - Usage: ynh_validate_ip4 --ip_address=ip_address - -

- -

- Arguments: -

    +- `-i`, `--ip_address=`: the ipv4 address to check -
  • -i, --ip_address= : the ipv4 address to check
    • - - -
-

- + -

- Returns: 0 for valid ipv4 addresses, 1 otherwise -

+ +**Returns**: 0 for valid ipv4 addresses, 1 otherwise -

- Example: ynh_validate_ip4 111.222.333.444 -

+**Example**: `ynh_validate_ip4 111.222.333.444` -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/network#L99) +[/details] +---------------- +**ynh_validate_ip6** +[details summary="Validate an IPv6 address" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_validate_ip6 --ip_address=ip_address` + -
-
-
-
ynh_validate_ip6
-
Validate an IPv6 address
-
-
-
-

- - Usage: ynh_validate_ip6 --ip_address=ip_address +**Arguments**: -

- -

- Arguments: -

    - - -
  • -i, --ip_address= : the ipv6 address to check
    • +- `-i`, `--ip_address=`: the ipv6 address to check -
-

- + -

- Returns: 0 for valid ipv6 addresses, 1 otherwise -

+ +**Returns**: 0 for valid ipv6 addresses, 1 otherwise -

- Example: ynh_validate_ip6 2000:dead:beef::1 -

+**Example**: `ynh_validate_ip6 2000:dead:beef::1` -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

-

- Dude, show me the code ! -

- -
-
- -
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/network#L121) +[/details] +---------------- -

nginx

+### NGINX +**ynh_add_nginx_config** +[details summary="Create a dedicated nginx config" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_add_nginx_config "list of others variables to replace"` + -
-
-
-
ynh_add_nginx_config
-
Create a dedicated nginx config
-
-
-
-

- - Usage: ynh_add_nginx_config "list of others variables to replace" +**Arguments**: -

- -

- Arguments: -

    - - -
  • list : (Optional) list of others variables to replace separated by spaces. For example : 'path_2 port_2 ...'
    • +- `list`: (Optional) list of others variables to replace separated by spaces. For example : 'path_2 port_2 ...' -
-

- + -

- Details: -

- This will use a template in ../conf/nginx.conf
__PATH__ by $path_url
__DOMAIN__ by $domain
__PORT__ by $port
__NAME__ by $app
__FINALPATH__ by $final_path
__PHPVERSION__ by $YNH_PHP_VERSION ($YNH_PHP_VERSION is either the default php version or the version defined for the app)

And dynamic variables (from the last example) :
__PATH_2__ by $path_2
__PORT_2__ by $port_2

Requires YunoHost version 2.7.2 or higher.
Requires YunoHost version 2.7.13 or higher for dynamic variables

-

-

-

- Dude, show me the code ! -

- -
-
-
+**Details**: +This will use a template in ../conf/nginx.conf
\_\_PATH\_\_ by $path\_url
\_\_DOMAIN\_\_ by $domain
\_\_PORT\_\_ by $port
\_\_NAME\_\_ by $app
\_\_FINALPATH\_\_ by $final\_path
\_\_PHPVERSION\_\_ by $YNH\_PHP\_VERSION ($YNH\_PHP\_VERSION is either the default php version or the version defined for the app)

And dynamic variables (from the last example) :
\_\_PATH\_2\_\_ by $path\_2
\_\_PORT\_2\_\_ by $port\_2

Requires YunoHost version 2.7.2 or higher.
Requires YunoHost version 2.7.13 or higher for dynamic variables

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/nginx#L23) +[/details] +---------------- +**ynh_remove_nginx_config** +[details summary="Remove the dedicated nginx config" class="helper-card-subtitle text-muted"] +

-
-
-
-
ynh_remove_nginx_config
-
Remove the dedicated nginx config
-
-
-
-

- - Usage: ynh_remove_nginx_config - -

+**Usage**: `ynh_remove_nginx_config` -

- Details: -

- Requires YunoHost version 2.7.2 or higher.

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- +**Details**: +Requires YunoHost version 2.7.2 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/nginx#L77) +[/details] +---------------- -

nodejs

+### NODEJS +**ynh_use_nodejs** +[details summary="Load the version of node for an app, and set variables." class="helper-card-subtitle text-muted"] +

-
-
-
-
ynh_use_nodejs
-
Load the version of node for an app, and set variables.
-
-
-
-

- - Usage: ynh_use_nodejs - -

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

-

-

-

- Dude, show me the code ! -

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

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/nodejs#L68) +[/details] +---------------- +**ynh_install_nodejs** +[details summary="Install a specific version of nodejs" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_install_nodejs --nodejs_version=nodejs_version` + -
-
-
-
ynh_install_nodejs
-
Install a specific version of nodejs
-
-
-
-

- - Usage: ynh_install_nodejs --nodejs_version=nodejs_version +**Arguments**: -

- -

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

-

-

-

- Dude, show me the code ! -

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

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/nodejs#L106) +[/details] +---------------- +**ynh_remove_nodejs** +[details summary="Remove the version of node used by the app." class="helper-card-subtitle text-muted"] +

-
-
-
-
ynh_remove_nodejs
-
Remove the version of node used by the app.
-
-
-
-

- - Usage: ynh_remove_nodejs - -

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

-

-

-

- Dude, show me the code ! -

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

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/nodejs#L187) +[/details] +---------------- -

permission

+### PERMISSION +**ynh_permission_create** +[details summary="Create a new permission for the app" class="helper-card-subtitle text-muted"] +

-
-
-
-
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] +**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] | Not that if 'show_tile' is enabled, this URL will be the URL of the tile. | Default is "APP_LABEL (permission name)". | Default is false (for the permission different than 'main'). | won't be able to add or remove the visitors group of this permission. -| By default it's 'false' +| By default it's 'false'` + + +**Arguments**: -

- -

- Arguments: -

    +- `-p,`: - the name for the permission (by default a permission named "main" already exist) -
  • -p, : - the name for the permission (by default a permission named "main" already exist)
    • - - - -
  • -u, : - (optional) URL for which access will be allowed/forbidden.
    • - - - -
  • -A, : - (optional) List of additional URL for which access will be allowed/forbidden
    • - - - -
  • -h, : - (optional) Define for the URL of this permission, if SSOwat pass the authentication header to the application. Default is true
    • - - - -
  • -a, : - (optional) A list of group/user to allow for the permission
    • - - - -
  • -l, : - (optional) Define a name for the permission. This label will be shown on the SSO and in the admin.
    • - - - -
  • -t, : - (optional) Define if a tile will be shown in the SSO. If yes the name of the tile will be the 'label' parameter.
    • - - - -
  • -P, : - (optional) Define if this permission is protected. If it is protected the administrator
    • - - -
-

- - - - - -

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

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - -
-
-
-
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" + +- `-u,`: - (optional) URL for which access will be allowed/forbidden. + -

- -

- Arguments: -

    +- `-A,`: - (optional) List of additional URL for which access will be allowed/forbidden -
  • -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.

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - -
-
-
-
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 + +- `-h,`: - (optional) Define for the URL of this permission, if SSOwat pass the authentication header to the application. Default is true + -

- -

- Arguments: -

    +- `-a,`: - (optional) A list of group/user to allow for the permission -
  • -p, --permission= : the permission to check
    • - - -
-

- - - - - -

- Details: -

- Requires YunoHost version 3.7.0 or higher.

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - -
-
-
-
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" ]] + +- `-l,`: - (optional) Define a name for the permission. This label will be shown on the SSO and in the admin. + + + +- `-t,`: - (optional) Define if a tile will be shown in the SSO. If yes the name of the tile will be the 'label' parameter. + + + +- `-P,`: - (optional) Define if this permission is protected. If it is protected the administrator + + + + + + + + +**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.

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/permission#L69) +[/details] +---------------- + +**ynh_permission_delete** +[details summary="Remove a permission for the app (note that when the app is removed all permission is automatically removed)" class="helper-card-subtitle text-muted"] +

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

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/permission#L164) +[/details] +---------------- + +**ynh_permission_exists** +[details summary="Check if a permission exists" class="helper-card-subtitle text-muted"] +

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

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/permission#L181) +[/details] +---------------- + +**ynh_permission_url** +[details summary="Redefine the url associated to a permission" class="helper-card-subtitle text-muted"] +

+ +**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] -| Note that if you want to remove url you can pass an empty sting as arguments (""). +| Note that if you want to remove url you can pass an empty sting as arguments ("").` + + +**Arguments**: -

- -

- Arguments: -

    +- `-p,`: - the name for the permission (by default a permission named "main" is removed automatically when the app is removed) -
  • -p, : - the name for the permission (by default a permission named "main" is removed automatically when the app is removed)
    • - - - -
  • -u, : - (optional) URL for which access will be allowed/forbidden.
    • - - - -
  • -a, : - (optional) List of additional url to add for which access will be allowed/forbidden.
    • - - - -
  • -r, : - (optional) List of additional url to remove for which access will be allowed/forbidden
    • - - - -
  • -h, : - (optional) Define for the URL of this permission, if SSOwat pass the authentication header to the application
    • - - - -
  • -c, : - (optional) Clean all urls (url and additional_urls)
    • - - -
-

- - - - - -

- Details: -

- Requires YunoHost version 3.7.0 or higher.

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - -
-
-
-
ynh_permission_update
-
Update a permission for the app
-
-
-
-

- Usage: ynh_permission_update --permission "permission" [--add="group" ["group" ...]] [--remove="group" ["group" ...]] + +- `-u,`: - (optional) URL for which access will be allowed/forbidden. + + + +- `-a,`: - (optional) List of additional url to add for which access will be allowed/forbidden. + + + +- `-r,`: - (optional) List of additional url to remove for which access will be allowed/forbidden + + + +- `-h,`: - (optional) Define for the URL of this permission, if SSOwat pass the authentication header to the application + + + +- `-c,`: - (optional) Clean all urls (url and additional_urls) + + + + + + + + +**Details**: +Requires YunoHost version 3.7.0 or higher.

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/permission#L204) +[/details] +---------------- + +**ynh_permission_update** +[details summary="Update a permission for the app" class="helper-card-subtitle text-muted"] +

+ +**Usage**: `ynh_permission_update --permission "permission" [--add="group" ["group" ...]] [--remove="group" ["group" ...]] [--label="label"] [--show_tile=true|false] [--protected=true|false] -| won't be able to add or remove the visitors group of this permission. +| won't be able to add or remove the visitors group of this permission.` + + +**Arguments**: -

- -

- Arguments: -

    +- `-p,`: - the name for the permission (by default a permission named "main" already exist) -
  • -p, : - the name for the permission (by default a permission named "main" already exist)
    • - - - -
  • -a, : - the list of group or users to enable add to the permission
    • - - - -
  • -r, : - the list of group or users to remove from the permission
    • - - - -
  • -l, : - (optional) Define a name for the permission. This label will be shown on the SSO and in the admin.
    • - - - -
  • -t, : - (optional) Define if a tile will be shown in the SSO
    • - - - -
  • -P, : - (optional) Define if this permission is protected. If it is protected the administrator
    • - - -
-

- - - - - -

- Details: -

- Requires YunoHost version 3.7.0 or higher.

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - -
-
-
-
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 + +- `-a,`: - the list of group or users to enable add to the permission + -

- -

- Arguments: -

    +- `-r,`: - the list of group or users to remove from the permission -
  • -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.

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - -
-
-
-
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 + +- `-l,`: - (optional) Define a name for the permission. This label will be shown on the SSO and in the admin. + -

- - - - - -

- Details: -

- Requires YunoHost version 4.1.2 or higher.

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - -
-
-
-
ynh_legacy_permissions_delete_all
-
Remove all legacy permissions
-
-
-
-

+ +- `-t,`: - (optional) Define if a tile will be shown in the SSO + - Usage: ynh_legacy_permissions_delete_all + +- `-P,`: - (optional) Define if this permission is protected. If it is protected the administrator + -

-

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

+ +**Details**: +Requires YunoHost version 3.7.0 or higher.

-

- Dude, show me the code ! -

-
-
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/permission#L280) +[/details] +---------------- -
+**ynh_permission_has_user** +[details summary="Check if a permission has an user" class="helper-card-subtitle text-muted"] +

+**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` + - - -

php

- - - -
-
-
-
ynh_add_fpm_config
-
Create a dedicated PHP-FPM config
-
-
-
-

+**Arguments**: - Usage: 1: ynh_add_fpm_config [--phpversion=7.X] [--use_template] [--package=packages] [--dedicated_service] + +- `-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.

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/permission#L355) +[/details] +---------------- + +**ynh_legacy_permissions_exists** +[details summary="Check if a legacy permissions exist" class="helper-card-subtitle text-muted"] +

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

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/permission#L378) +[/details] +---------------- + +**ynh_legacy_permissions_delete_all** +[details summary="Remove all legacy permissions" class="helper-card-subtitle text-muted"] +

+ +**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.` + + + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/permission#L399) +[/details] +---------------- + + +### PHP + +**ynh_add_fpm_config** +[details summary="Create a dedicated PHP-FPM config" class="helper-card-subtitle text-muted"] +

+ +**Usage**: `1: ynh_add_fpm_config [--phpversion=7.X] [--use_template] [--package=packages] [--dedicated_service] 2: ynh_add_fpm_config [--phpversion=7.X] --usage=usage --footprint=footprint [--package=packages] [--dedicated_service] low - Less than 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. Or specify exactly the footprint, the load of the service as MB by pool instead of having a standard value. To have this value, use the following command and stress the service. -watch -n0.5 ps -o user,cmd,%cpu,rss -u APP - -

+watch -n0.5 ps -o user,cmd,%cpu,rss -u APP` -

- Arguments: -

    - - -
  • -v, --phpversion= : Version of PHP to use.
    • - - - -
  • -t, --use_template : Use this helper in template mode.
    • - - - -
  • -p, --package= : Additionnal PHP packages to install
    • - - - -
  • -d, --dedicated_service : Use a dedicated PHP-FPM service instead of the common one.
    • - - - -
  • -v, --phpversion= : Version of PHP to use.
    • - - - -
  • -f, --footprint= : Memory footprint of the service (low/medium/high).
    • - - - -
  • -u, --usage= : Expected usage of the service (low/medium/high).
    • - - - -
  • -p, --package= : Additionnal PHP packages to install for a specific version of PHP
    • - - - -
  • -d, --dedicated_service : Use a dedicated PHP-FPM service instead of the common one.
    • - - -
-

- - - - - -

- Details: -

- -----------------------------------------------------------------------------

The footprint of the service will be used to defined the maximum footprint we can allow, which is half the maximum RAM.
So it will be used to defined 'pm.max_children'
A lower value for the footprint will allow more children for 'pm.max_children'. And so for
'pm.start_servers', 'pm.min_spare_servers' and 'pm.max_spare_servers' which are defined from the
value of 'pm.max_children'
NOTE: 'pm.max_children' can't exceed 4 times the number of processor's cores.

The usage value will defined the way php will handle the children for the pool.
A value set as 'low' will set the process manager to 'ondemand'. Children will start only if the
service is used, otherwise no child will stay alive. This config gives the lower footprint when the
service is idle. But will use more proc since it has to start a child as soon it's used.
Set as 'medium', the process manager will be at dynamic. If the service is idle, a number of children
equal to pm.min_spare_servers will stay alive. So the service can be quick to answer to any request.
The number of children can grow if needed. The footprint can stay low if the service is idle, but
not null. The impact on the proc is a little bit less than 'ondemand' as there's always a few
children already available.
Set as 'high', the process manager will be set at 'static'. There will be always as many children as
'pm.max_children', the footprint is important (but will be set as maximum a quarter of the maximum
RAM) but the impact on the proc is lower. The service will be quick to answer as there's always many
children ready to answer.

Requires YunoHost version 2.7.2 or higher.
Requires YunoHost version 3.5.1 or higher for the argument --phpversion
Requires YunoHost version 3.8.1 or higher for the arguments --use_template, --usage, --footprint, --package and --dedicated_service

-

-

- -

- Dude, show me the code ! -

-
-
- -
- - - -
-
-
-
ynh_remove_fpm_config
-
Remove the dedicated PHP-FPM config
-
-
-
-

- - Usage: ynh_remove_fpm_config - -

- - - - - -

- Details: -

- Requires YunoHost version 2.7.2 or higher.

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - - -

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:

    +**Arguments**: - ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;" +- `-v`, `--phpversion=`: Version of PHP to use. -
    - ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql +- `-t`, `--use_template`: Use this helper in template mode. -
    -
-

- - -

- Details: -

- Requires YunoHost version 3.5.0 or higher.

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - -
-
-
-
ynh_psql_execute_as_root
-
Execute a command as root user
-
-
-
-

+ +- `-p`, `--package=`: Additionnal PHP packages to install + - Usage: ynh_psql_execute_as_root --sql=sql [--database=database] + +- `-d`, `--dedicated_service`: Use a dedicated PHP-FPM service instead of the common one. + -

- -

- Arguments: -

    +- `-v`, `--phpversion=`: Version of PHP to use. -
  • -s, --sql= : the SQL command to execute
    • - - - -
  • -d, --database= : the database to connect to
    • - - -
-

- - - - - -

- Details: -

- Requires YunoHost version 3.5.0 or higher.

-

-

- -

- 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=file [--database=database] + +- `-f`, `--footprint=`: Memory footprint of the service (low/medium/high). + -

- -

- Arguments: -

    +- `-u`, `--usage=`: Expected usage of the service (low/medium/high). -
  • -f, --file= : the file containing SQL commands
    • - - - -
  • -d, --database= : the database to connect to
    • - - -
-

- - - - - -

- Details: -

- Requires YunoHost version 3.5.0 or higher.

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - -
-
-
-
ynh_psql_dump_db
-
Dump a database
-
-
-
-

- Usage: ynh_psql_dump_db --database=database + +- `-p`, `--package=`: Additionnal PHP packages to install for a specific version of PHP + -

- -

- Arguments: -

    +- `-d`, `--dedicated_service`: Use a dedicated PHP-FPM service instead of the common one. -
  • -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.

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - -
-
-
-
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 + + + + + + +**Details**: +-----------------------------------------------------------------------------

The footprint of the service will be used to defined the maximum footprint we can allow, which is half the maximum RAM.
So it will be used to defined 'pm.max\_children'
A lower value for the footprint will allow more children for 'pm.max\_children'. And so for
'pm.start\_servers', 'pm.min\_spare\_servers' and 'pm.max\_spare\_servers' which are defined from the
value of 'pm.max\_children'
NOTE: 'pm.max\_children' can't exceed 4 times the number of processor's cores.

The usage value will defined the way php will handle the children for the pool.
A value set as 'low' will set the process manager to 'ondemand'. Children will start only if the
service is used, otherwise no child will stay alive. This config gives the lower footprint when the
service is idle. But will use more proc since it has to start a child as soon it's used.
Set as 'medium', the process manager will be at dynamic. If the service is idle, a number of children
equal to pm.min\_spare\_servers will stay alive. So the service can be quick to answer to any request.
The number of children can grow if needed. The footprint can stay low if the service is idle, but
not null. The impact on the proc is a little bit less than 'ondemand' as there's always a few
children already available.
Set as 'high', the process manager will be set at 'static'. There will be always as many children as
'pm.max\_children', the footprint is important (but will be set as maximum a quarter of the maximum
RAM) but the impact on the proc is lower. The service will be quick to answer as there's always many
children ready to answer.

Requires YunoHost version 2.7.2 or higher.
Requires YunoHost version 3.5.1 or higher for the argument --phpversion
Requires YunoHost version 3.8.1 or higher for the arguments --use\_template, --usage, --footprint, --package and --dedicated\_service

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/php#L61) +[/details] +---------------- + +**ynh_remove_fpm_config** +[details summary="Remove the dedicated PHP-FPM config" class="helper-card-subtitle text-muted"] +

+ +**Usage**: `ynh_remove_fpm_config` + + + + + + +**Details**: +Requires YunoHost version 2.7.2 or higher.

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/php#L288) +[/details] +---------------- + + +### POSTGRESQL + +**ynh_psql_connect_as** +[details summary="Open a connection as a user" class="helper-card-subtitle text-muted"] +

+ +**Usage**: `ynh_psql_connect_as --user=user --password=password [--database=database]` + + +**Arguments**: -

- -

- Arguments: -

    +- `-u`, `--user=`: the user name to connect as -
  • -u, --user= : the user for which to check existence
    • - - -
-

- - - - - -

- Details: -

- Requires YunoHost version 3.5.0 or higher.

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - -
-
-
-
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 + +- `-p`, `--password=`: the user password + -

- -

- Arguments: -

    +- `-d`, `--database=`: the database to connect to -
  • -d, --database= : the database for which to check existence
    • - - -
-

- - - - - -

- Details: -

- Requires YunoHost version 3.5.0 or higher.

-

-

- -

- 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 --db_user=user --db_name=name [--db_pwd=pwd] + + + + + +**Examples**: -

- -

- Arguments: -

    +- ` ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;"` -
  • -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.

-

-

- -

- Dude, show me the code ! -

- -
-
- -
- - - -
-
-
-
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 + +- ` ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql` + -

- -

- Arguments: -

    - - -
  • -u, --db_user= : Owner of the database
    • - - - -
  • -n, --db_name= : Name of the database
    • - - -
-

- - - -

- Details: -

- Requires YunoHost version 2.7.13 or higher.

-

-

- -

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 3.5.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/postgresql#L18) +[/details] +---------------- +**ynh_psql_execute_as_root** +[details summary="Execute a command as root user" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_psql_execute_as_root --sql=sql [--database=database]` + -
-
-
-
ynh_psql_test_if_first_run
-
Create a master password and set up global settings +**Arguments**: + + +- `-s`, `--sql=`: the SQL command to execute + + + +- `-d`, `--database=`: the database to connect to + + + + + + + + +**Details**: +Requires YunoHost version 3.5.0 or higher.

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/postgresql#L39) +[/details] +---------------- + +**ynh_psql_execute_file_as_root** +[details summary="Execute a command from a file as root user" class="helper-card-subtitle text-muted"] +

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

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/postgresql#L65) +[/details] +---------------- + +**ynh_psql_dump_db** +[details summary="Dump a database" class="helper-card-subtitle text-muted"] +

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

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/postgresql#L137) +[/details] +---------------- + +**ynh_psql_user_exists** +[details summary="Check if a psql user exists" class="helper-card-subtitle text-muted"] +

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

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/postgresql#L170) +[/details] +---------------- + +**ynh_psql_database_exists** +[details summary="Check if a psql database exists" class="helper-card-subtitle text-muted"] +

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

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/postgresql#L193) +[/details] +---------------- + +**ynh_psql_setup_db** +[details summary="Create a database, an user and its password. Then store the password in the app's config" class="helper-card-subtitle text-muted"] +

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

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/postgresql#L232) +[/details] +---------------- + +**ynh_psql_remove_db** +[details summary="Remove a database if it exists, and the associated user" class="helper-card-subtitle text-muted"] +

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

+ + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/postgresql#L263) +[/details] +---------------- + +**ynh_psql_test_if_first_run** +[details summary="Create a master password and set up global settings It also make sure that postgresql is installed and running -Please always call this script in install and restore scripts
-
-
-
-

- - Usage: ynh_psql_test_if_first_run - -

- +Please always call this script in install and restore scripts" class="helper-card-subtitle text-muted"] +

+ +**Usage**: `ynh_psql_test_if_first_run` -

- Details: -

- Requires YunoHost version 2.7.13 or higher.

-

-

-

- Dude, show me the code ! -

- -
-
- -
+**Details**: +Requires YunoHost version 2.7.13 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/postgresql#L295) +[/details] +---------------- -

setting

+### SETTING +**ynh_app_setting_get** +[details summary="Get an application setting" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_app_setting_get --app=app --key=key` + -
-
-
-
ynh_app_setting_get
-
Get an application setting
-
-
-
-

- - Usage: ynh_app_setting_get --app=app --key=key +**Arguments**: -

- -

- Arguments: -

    - -
  • -a, --app= : the application id
    • +- `-a`, `--app=`: the application id + +- `-k`, `--key=`: the setting to get -
  • -k, --key= : the setting to get
    • - - -
-

- + -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/setting#L10) +[/details] +---------------- +**ynh_app_setting_set** +[details summary="Set an application setting" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_app_setting_set --app=app --key=key --value=value` + -
-
-
-
ynh_app_setting_set
-
Set an application setting
-
-
-
-

- - Usage: ynh_app_setting_set --app=app --key=key --value=value +**Arguments**: -

- -

- Arguments: -

    - -
  • -a, --app= : the application id
    • - - - -
  • -k, --key= : the setting name to set
    • +- `-a`, `--app=`: the application id + +- `-k`, `--key=`: the setting name to set -
  • -v, --value= : the setting value to set
    • + +- `-v`, `--value=`: the setting value to set -
-

- + -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/setting#L34) +[/details] +---------------- +**ynh_app_setting_delete** +[details summary="Delete an application setting" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_app_setting_delete --app=app --key=key` + -
-
-
-
ynh_app_setting_delete
-
Delete an application setting
-
-
-
-

- - Usage: ynh_app_setting_delete --app=app --key=key +**Arguments**: -

- -

- Arguments: -

    - - -
  • -a, --app= : the application id
    • +- `-a`, `--app=`: the application id + -
  • -k, --key= : the setting to delete
    • - +- `-k`, `--key=`: the setting to delete -
-

- + -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/setting#L58) +[/details] +---------------- +**ynh_webpath_available** +[details summary="Check availability of a web path" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_webpath_available --domain=domain --path_url=path` + -
-
-
-
ynh_webpath_available
-
Check availability of a web path
-
-
-
-

- - Usage: ynh_webpath_available --domain=domain --path_url=path +**Arguments**: -

- -

- Arguments: -

    - - -
  • -d, --domain= : the domain/host of the url
    • +- `-d`, `--domain=`: the domain/host of the url + -
  • -p, --path_url= : the web path to check the availability of
    • - +- `-p`, `--path_url=`: the web path to check the availability of -
-

- + -

- Example: ynh_webpath_available --domain=some.domain.tld --path_url=/coffee -

+**Example**: `ynh_webpath_available --domain=some.domain.tld --path_url=/coffee` -

- Details: -

- Requires YunoHost version 2.6.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.6.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/setting#L118) +[/details] +---------------- +**ynh_webpath_register** +[details summary="Register/book a web path for an app" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_webpath_register --app=app --domain=domain --path_url=path` + -
-
-
-
ynh_webpath_register
-
Register/book a web path for an app
-
-
-
-

- - Usage: ynh_webpath_register --app=app --domain=domain --path_url=path +**Arguments**: -

- -

- Arguments: -

    - - -
  • -a, --app= : the app for which the domain should be registered
    • - - -
  • -d, --domain= : the domain/host of the web path
    • +- `-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
    • + +- `-p`, `--path_url=`: the web path to be registered -
-

- + -

- Example: ynh_webpath_register --app=wordpress --domain=some.domain.tld --path_url=/coffee -

+**Example**: `ynh_webpath_register --app=wordpress --domain=some.domain.tld --path_url=/coffee` -

- Details: -

- Requires YunoHost version 2.6.4 or higher.

-

-

-

- Dude, show me the code ! -

- -
-
- -
+**Details**: +Requires YunoHost version 2.6.4 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/setting#L140) +[/details] +---------------- -

string

+### STRING +**ynh_string_random** +[details summary="Generate a random string" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_string_random [--length=string_length]` + -
-
-
-
ynh_string_random
-
Generate a random string
-
-
-
-

+**Arguments**: - Usage: ynh_string_random [--length=string_length] - -

- -

- Arguments: -

    +- `-l`, `--length=`: the string length to generate (default: 24) -
  • -l, --length= : the string length to generate (default: 24)
    • - - -
-

- + -

- Returns: the generated string -

+ +**Returns**: the generated string -

- Example: pwd=$(ynh_string_random --length=8) -

+**Example**: `pwd=$(ynh_string_random --length=8)` -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/string#L12) +[/details] +---------------- +**ynh_replace_string** +[details summary="Substitute/replace a string (or expression) by another in a file" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_replace_string --match_string=match_string --replace_string=replace_string --target_file=target_file` + -
-
-
-
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**: -

- -

- Arguments: -

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

-

-

-

- Dude, show me the code ! -

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

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/string#L38) +[/details] +---------------- +**ynh_replace_special_string** +[details summary="Substitute/replace a special string by another in a file" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_replace_special_string --match_string=match_string --replace_string=replace_string --target_file=target_file` + -
-
-
-
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**: -

- -

- Arguments: -

    +- `-m`, `--match_string=`: String to be searched and replaced in the file -
  • -m, --match_string= : String to be searched and replaced in the file
    • - - - -
  • -r, --replace_string= : String that will replace matches
    • - + +- `-r`, `--replace_string=`: String that will replace matches -
  • -t, --target_file= : File in which the string will be replaced.
    • + +- `-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.

-

-

-

- Dude, show me the code ! -

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

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/string#L67) +[/details] +---------------- +**ynh_sanitize_dbid** +[details summary="Sanitize a string intended to be the name of a database +(More specifically : replace - and . by _)" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_sanitize_dbid --db_name=name` + -
-
-
-
ynh_sanitize_dbid
-
Sanitize a string intended to be the name of a database -(More specifically : replace - and . by _)
-
-
-
-

+**Arguments**: - Usage: ynh_sanitize_dbid --db_name=name - -

- -

- Arguments: -

    - -
  • -n, --db_name= : name to correct/sanitize
    • +- `-n`, `--db_name=`: name to correct/sanitize - -
-

- + -

- Returns: the corrected name -

+ +**Returns**: the corrected name -

- Example: dbname=$(ynh_sanitize_dbid $app) -

+**Example**: `dbname=$(ynh_sanitize_dbid $app)` -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

-

- Dude, show me the code ! -

- -
-
- -
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/string#L98) +[/details] +---------------- -

systemd

+### SYSTEMD +**ynh_add_systemd_config** +[details summary="Create a dedicated systemd config" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_add_systemd_config [--service=service] [--template=template] +ynh_add_systemd_config [--service=service] [--template=template] [--others_var="list of others variables to replace"]` + -
-
-
-
ynh_add_systemd_config
-
Create a dedicated systemd config
-
-
-
-

- - Usage: ynh_add_systemd_config [--service=service] [--template=template] -ynh_add_systemd_config [--service=service] [--template=template] [--others_var="list of others variables to replace"] +**Arguments**: -

- -

- Arguments: -

    - - -
  • -s, --service= : Service name (optionnal, $app by default)
    • +- `-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)
    • - - +- `-t`, `--template=`: Name of template file (optionnal, this is 'systemd' by default, meaning ./conf/systemd.service will be used as template) -
  • -v, --others_var= : List of others variables to replace separated by a space. For example: 'var_1 var_2 ...'
    • + +- `-v`, `--others_var=`: List of others variables to replace separated by a space. For example: 'var_1 var_2 ...' -
-

- + -

- Details: -

- This will use the template ../conf/.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

And dynamic variables (from the last example) :
__VAR_1__ by $var_1
__VAR_2__ by $var_2

Requires YunoHost version 2.7.11 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**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

And dynamic variables (from the last example) :
\_\_VAR\_1\_\_ by $var\_1
\_\_VAR\_2\_\_ by $var\_2

Requires YunoHost version 2.7.11 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/systemd#L24) +[/details] +---------------- +**ynh_remove_systemd_config** +[details summary="Remove the dedicated systemd config" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_remove_systemd_config [--service=service]` + -
-
-
-
ynh_remove_systemd_config
-
Remove the dedicated systemd config
-
-
-
-

+**Arguments**: - Usage: ynh_remove_systemd_config [--service=service] - -

- -

- Arguments: -

    +- `-s`, `--service=`: Service name (optionnal, $app by default) -
  • -s, --service= : Service name (optionnal, $app by default)
    • - - -
-

- + -

- Details: -

- Requires YunoHost version 2.7.2 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.7.2 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/systemd#L71) +[/details] +---------------- +**ynh_systemd_action** +[details summary="Start (or other actions) a service, print a log in case of failure and optionnaly wait until the service is completely started" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_systemd_action [--service_name=service_name] [--action=action] [ [--line_match="line to match"] [--log_path=log_path] [--timeout=300] [--length=20] ]` + -
-
-
-
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**: -

- -

- Arguments: -

    - - -
  • -n, --service_name= : Name of the service to start. Default : $app
    • +- `-n`, `--service_name=`: Name of the service to start. Default : $app + -
  • -a, --action= : Action to perform with systemctl. Default: start
    • - - - -
  • -l, --line_match= : Line to match - The line to find in the log to attest the service have finished to boot. If not defined it don't wait until the service is completely started. WARNING: When using --line_match, you should always add `ynh_clean_check_starting` into your `ynh_clean_setup` at the beginning of the script. Otherwise, tail will not stop in case of failure of the script. The script will then hang forever.
    • - - +- `-a`, `--action=`: Action to perform with systemctl. Default: start -
  • -p, --log_path= : Log file - Path to the log file. Default : /var/log/$app/$app.log
    • + +- `-l`, `--line_match=`: Line to match - The line to find in the log to attest the service have finished to boot. If not defined it don't wait until the service is completely started. WARNING: When using --line_match, you should always add `ynh_clean_check_starting` into your `ynh_clean_setup` at the beginning of the script. Otherwise, tail will not stop in case of failure of the script. The script will then hang forever. + -
  • -t, --timeout= : Timeout - The maximum time to wait before ending the watching. Default : 300 seconds.
    • +- `-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
    • + +- `-e`, `--length=`: Length of the error log : Default : 20 -
-

- + -

- Details: -

- Requires YunoHost version 3.5.0 or higher.

-

-

-

- Dude, show me the code ! -

- -
-
-
+**Details**: +Requires YunoHost version 3.5.0 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/systemd#L101) +[/details] +---------------- +**ynh_clean_check_starting** +[details summary="Clean temporary process and file used by ynh_check_starting +(usually used in ynh_clean_setup scripts)" class="helper-card-subtitle text-muted"] +

-
-
-
-
ynh_clean_check_starting
-
Clean temporary process and file used by ynh_check_starting -(usually used in ynh_clean_setup scripts)
-
-
-
-

- - Usage: ynh_clean_check_starting - -

- +**Usage**: `ynh_clean_check_starting` -

- Details: -

- Requires YunoHost version 3.5.0 or higher.

-

-

-

- Dude, show me the code ! -

- -
-
- -
+**Details**: +Requires YunoHost version 3.5.0 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/systemd#L203) +[/details] +---------------- -

user

+### USER +**ynh_user_exists** +[details summary="Check if a YunoHost user exists" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_user_exists --username=username +| exit: Return 1 if the user doesn't exist, 0 otherwise` + -
-
-
-
ynh_user_exists
-
Check if a YunoHost user exists
-
-
-
-

- - Usage: ynh_user_exists --username=username -| exit: Return 1 if the user doesn't exist, 0 otherwise +**Arguments**: -

- -

- Arguments: -

    - - -
  • -u, --username= : the username to check
    • +- `-u`, `--username=`: the username to check -
-

- + -

- Example: ynh_user_exists 'toto' || exit 1 -

+**Example**: `ynh_user_exists 'toto' || exit 1` -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/user#L12) +[/details] +---------------- +**ynh_user_get_info** +[details summary="Retrieve a YunoHost user information" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_user_get_info --username=username --key=key` + -
-
-
-
ynh_user_get_info
-
Retrieve a YunoHost user information
-
-
-
-

- - Usage: ynh_user_get_info --username=username --key=key +**Arguments**: -

- -

- Arguments: -

    - - -
  • -u, --username= : the username to retrieve info from
    • +- `-u`, `--username=`: the username to retrieve info from + -
  • -k, --key= : the key to retrieve
    • - +- `-k`, `--key=`: the key to retrieve -
-

- + -

- Returns: string - the key's value -

+ +**Returns**: string - the key's value -

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

+**Example**: `mail=$(ynh_user_get_info 'toto' 'mail')` -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

-

- Dude, show me the code ! -

- -
-
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/user#L33) +[/details] +---------------- +**ynh_user_list** +[details summary="Get the list of YunoHost users" class="helper-card-subtitle text-muted"] +

-
-
-
-
ynh_user_list
-
Get the list of YunoHost users
-
-
-
-

- - Usage: ynh_user_list - -

- +**Usage**: `ynh_user_list` -

- Returns: string - one username per line -

+ +**Returns**: string - one username per line -

- Example: for u in $(ynh_user_list); do ... -

+**Example**: `for u in $(ynh_user_list); do ...` -

- Details: -

- Requires YunoHost version 2.4.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.4.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/user#L53) +[/details] +---------------- +**ynh_system_user_exists** +[details summary="Check if a user exists on the system" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_system_user_exists --username=username +| exit: Return 1 if the user doesn't exist, 0 otherwise` + -
-
-
-
ynh_system_user_exists
-
Check if a user exists on the system
-
-
-
-

+**Arguments**: - Usage: ynh_system_user_exists --username=username -| exit: Return 1 if the user doesn't exist, 0 otherwise - -

- -

- Arguments: -

    - -
  • -u, --username= : the username to check
    • +- `-u`, `--username=`: the username to check - -
-

- + -

- Details: -

- Requires YunoHost version 2.2.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.2.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/user#L65) +[/details] +---------------- +**ynh_system_group_exists** +[details summary="Check if a group exists on the system" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_system_group_exists --group=group +| exit: Return 1 if the group doesn't exist, 0 otherwise` + -
-
-
-
ynh_system_group_exists
-
Check if a group exists on the system
-
-
-
-

+**Arguments**: - Usage: ynh_system_group_exists --group=group -| exit: Return 1 if the group doesn't exist, 0 otherwise - -

- -

- Arguments: -

    +- `-g`, `--group=`: the group to check -
  • -g, --group= : the group to check
    • - - -
-

- + -

- Details: -

- Requires YunoHost version 3.5.0.2 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 3.5.0.2 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/user#L83) +[/details] +---------------- +**ynh_system_user_create** +[details summary="Create a system user" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_system_user_create --username=user_name [--home_dir=home_dir] [--use_shell]` + -
-
-
-
ynh_system_user_create
-
Create a system user
-
-
-
-

- - Usage: ynh_system_user_create --username=user_name [--home_dir=home_dir] [--use_shell] +**Arguments**: -

- -

- Arguments: -

    - - -
  • -u, --username= : Name of the system user that will be create
    • +- `-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
    • - - +- `-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
    • + +- `-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:

    + +**Examples**: - Create a nextcloud user with no home directory and /usr/sbin/nologin login shell (hence no login capability) +- `Create a nextcloud user with no home directory and /usr/sbin/nologin login shell (hence no login capability)` -
    - ynh_system_user_create --username=nextcloud +- ` ynh_system_user_create --username=nextcloud` -
    - Create a discourse user using /var/www/discourse as home directory and the default login shell +- `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 +- ` ynh_system_user_create --username=discourse --home_dir=/var/www/discourse --use_shell` -
    -
-

- -

- Details: -

- Requires YunoHost version 2.6.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.6.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/user#L108) +[/details] +---------------- +**ynh_system_user_delete** +[details summary="Delete a system user" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_system_user_delete --username=user_name` + -
-
-
-
ynh_system_user_delete
-
Delete a system user
-
-
-
-

- - Usage: ynh_system_user_delete --username=user_name +**Arguments**: -

- -

- Arguments: -

    - - -
  • -u, --username= : Name of the system user that will be create
    • +- `-u`, `--username=`: Name of the system user that will be create -
-

- + -

- Details: -

- Requires YunoHost version 2.6.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
- -
+**Details**: +Requires YunoHost version 2.6.4 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/user#L144) +[/details] +---------------- +**ynh_exec_as** +[details summary="Execute a command as another user" class="helper-card-subtitle text-muted"] +

-
-
-
-
ynh_exec_as
-
Execute a command as another user
-
-
-
-

- - Usage: ynh_exec_as $USER COMMAND [ARG ...] - -

- +**Usage**: `ynh_exec_as $USER COMMAND [ARG ...]` -

- Details: -

- Requires YunoHost version 4.1.7 or higher.

-

-

-

- Dude, show me the code ! -

- -
-
- -
- +**Details**: +Requires YunoHost version 4.1.7 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/user#L172) +[/details] +---------------- -

utils

+### UTILS +**ynh_abort_if_errors** +[details summary="Exits if an error occurs during the execution of the script." class="helper-card-subtitle text-muted"] +

-
-
-
-
ynh_abort_if_errors
-
Exits if an error occurs during the execution of the script.
-
-
-
-

- - Usage: ynh_abort_if_errors - -

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

-

-

-

- Dude, show me the code ! -

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

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/utils#L54) +[/details] +---------------- +**ynh_setup_source** +[details summary="Download, check integrity, uncompress and patch the source from app.src" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_setup_source --dest_dir=dest_dir [--source_id=source_id]` + -
-
-
-
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**: -

- -

- Arguments: -

    - - -
  • -d, --dest_dir= : Directory where to setup sources
    • +- `-d`, `--dest_dir=`: Directory where to setup sources + -
  • -s, --source_id= : Name of the app, if the package contains more than one app
    • - +- `-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.

-

-

-

- Dude, show me the code ! -

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

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/utils#L105) +[/details] +---------------- +**ynh_local_curl** +[details summary="Curl abstraction to help with POST requests to local pages (such as installation forms)" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_local_curl "page_uri" "key1=value1" "key2=value2" ...` + -
-
-
-
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**: -

- -

- 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
    • +- `page_uri`: Path (relative to $path_url) of the page where POST data will be sent + -
  • key2=value2 : (Optionnal) Another POST key and corresponding value
    • +- `key1=value1`: (Optionnal) POST key and corresponding value + +- `key2=value2`: (Optionnal) Another POST key and corresponding value -
  • ... : (Optionnal) More POST keys and values
    • + +- `...`: (Optionnal) More POST keys and values -
-

- + -

- Example: ynh_local_curl "/install.php?installButton" "foo=$var1" "bar=$var2" -

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

-

-

-

- Dude, show me the code ! -

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

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/utils#L230) +[/details] +---------------- +**ynh_add_config** +[details summary="Create a dedicated config file from a template" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_add_config --template="template" --destination="destination"` + -
-
-
-
ynh_add_config
-
Create a dedicated config file from a template
-
-
-
-

+**Arguments**: - Usage: ynh_add_config --template="template" --destination="destination" - -

- -

- Arguments: -

    +- `-t`, `--template=`: Template config file to use -
  • -t, --template= : Template config file to use
    • - - - -
  • -d, --destination= : Destination of the config file
    • + +- `-d`, `--destination=`: Destination of the config file -
-

+ -

- Examples:

    + +**Examples**: - ynh_add_config --template=".env" --destination="$final_path/.env" +- ` ynh_add_config --template=".env" --destination="$final_path/.env"` -
    - ynh_add_config --template="../conf/.env" --destination="$final_path/.env" +- ` ynh_add_config --template="../conf/.env" --destination="$final_path/.env"` -
    - ynh_add_config --template="/etc/nginx/sites-available/default" --destination="etc/nginx/sites-available/mydomain.conf" +- ` ynh_add_config --template="/etc/nginx/sites-available/default" --destination="etc/nginx/sites-available/mydomain.conf"` -
    -
-

- -

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

-

-

-

- Dude, show me the code ! -

- -
-
-
+**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
\_\_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.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/utils#L302) +[/details] +---------------- +**ynh_get_debian_release** +[details summary="Fetch the Debian release codename" class="helper-card-subtitle text-muted"] +

-
-
-
-
ynh_get_debian_release
-
Fetch the Debian release codename
-
-
-
-

- - Usage: ynh_get_debian_release - -

- +**Usage**: `ynh_get_debian_release` -

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

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

- Details: -

- Requires YunoHost version 2.7.12 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.7.12 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/utils#L436) +[/details] +---------------- +**ynh_secure_remove** +[details summary="Remove a file or a directory securely" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_secure_remove --file=path_to_remove` + -
-
-
-
ynh_secure_remove
-
Remove a file or a directory securely
-
-
-
-

+**Arguments**: - Usage: ynh_secure_remove --file=path_to_remove - -

- -

- Arguments: -

    - -
  • -f, --file= : File or directory to remove
    • +- `-f`, `--file=`: File or directory to remove - -
-

- + -

- Details: -

- Requires YunoHost version 2.6.4 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 2.6.4 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/utils#L466) +[/details] +---------------- +**ynh_read_manifest** +[details summary="Read the value of a key in a ynh manifest file" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_read_manifest --manifest="manifest.json" --key="key"` + -
-
-
-
ynh_read_manifest
-
Read the value of a key in a ynh manifest file
-
-
-
-

+**Arguments**: - Usage: ynh_read_manifest --manifest="manifest.json" --key="key" - -

- -

- Arguments: -

    +- `-m`, `--manifest=`: Path of the manifest to read -
  • -m, --manifest= : Path of the manifest to read
    • - - - -
  • -k, --key= : Name of the key to find
    • + +- `-k`, `--key=`: Name of the key to find -
-

- + -

- Returns: the value associate to that key -

+ +**Returns**: the value associate to that key -

- Details: -

- Requires YunoHost version 3.5.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +Requires YunoHost version 3.5.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/utils#L547) +[/details] +---------------- +**ynh_app_upstream_version** +[details summary="Read the upstream version from the manifest, or from the env variable $YNH_APP_MANIFEST_VERSION if not given" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_app_upstream_version [--manifest="manifest.json"]` + -
-
-
-
ynh_app_upstream_version
-
Read the upstream version from the manifest, or from the env variable $YNH_APP_MANIFEST_VERSION if not given
-
-
-
-

- - Usage: ynh_app_upstream_version [--manifest="manifest.json"] +**Arguments**: -

- -

- Arguments: -

    - - -
  • -m, --manifest= : Path of the manifest to read
    • +- `-m`, `--manifest=`: Path of the manifest to read -
-

- + -

- Returns: the version number of the upstream app -

+ +**Returns**: the version number of the upstream app -

- Details: -

- 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

Requires YunoHost version 3.5.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +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

Requires YunoHost version 3.5.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/utils#L576) +[/details] +---------------- +**ynh_app_package_version** +[details summary="Read package version from the manifest" class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_app_package_version [--manifest="manifest.json"]` + -
-
-
-
ynh_app_package_version
-
Read package version from the manifest
-
-
-
-

+**Arguments**: - Usage: ynh_app_package_version [--manifest="manifest.json"] - -

- -

- Arguments: -

    +- `-m`, `--manifest=`: Path of the manifest to read -
  • -m, --manifest= : Path of the manifest to read
    • - - -
-

- + -

- Returns: the version number of the package -

+ +**Returns**: the version number of the package -

- Details: -

- 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

Requires YunoHost version 3.5.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
- -
+**Details**: +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

Requires YunoHost version 3.5.0 or higher.

+ +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/utils#L607) +[/details] +---------------- +**ynh_check_app_version_changed** +[details summary="Checks the app version to upgrade with the existing app version and returns:" class="helper-card-subtitle text-muted"] +

-
-
-
-
ynh_check_app_version_changed
-
Checks the app version to upgrade with the existing app version and returns:
-
-
-
-

- - Usage: ynh_check_app_version_changed - -

- +**Usage**: `ynh_check_app_version_changed` -

- Details: -

- - UPGRADE_PACKAGE if only the YunoHost package has changed
- UPGRADE_APP otherwise

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 use the parameter --force (or -F).
example: sudo yunohost app upgrade MyApp --force

Requires YunoHost version 3.5.0 or higher.

-

-

-

- Dude, show me the code ! -

-
-
+**Details**: +- UPGRADE\_PACKAGE if only the YunoHost package has changed
- UPGRADE\_APP otherwise

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 use the parameter --force (or -F).
example: sudo yunohost app upgrade MyApp --force

Requires YunoHost version 3.5.0 or higher.

+ -
+[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/adc83b4c9c2c30e9ef75f3609c538b646f91f1db/data/helpers.d/utils#L634) +[/details] +---------------- +**ynh_compare_current_package_version** +[details summary="Compare the current package version against another version given as an argument. +This is really useful when we need to do some actions only for some old package versions." class="helper-card-subtitle text-muted"] +

+**Usage**: `ynh_compare_current_package_version --comparison lt|le|eq|ne|ge|gt +| eq (equal), ne (not equal), ge (greater or equal), gt (greater than)` + -
-
-
-
ynh_compare_current_package_version
-
Compare the current package version against another version given as an argument. -This is really useful when we need to do some actions only for some old package versions.
-
-
-
-

- - Usage: ynh_compare_current_package_version --comparison lt|le|eq|ne|ge|gt -| eq (equal), ne (not equal), ge (greater or equal), gt (greater than) +**Arguments**: -

- -

- Arguments: -

    - -
  • --comparison : Comparison type. Could be : lt (lower than), le (lower or equal),
    • +- `--comparison`: Comparison type. Could be : lt (lower than), le (lower or equal), + +- `--version`: The version to compare. Need to be a version in the yunohost package version type (like 2.3.1~ynh4) -
  • --version : The version to compare. Need to be a version in the yunohost package version type (like 2.3.1~ynh4)
    • - - -
-

- + -

- Example: ynh_compare_current_package_version --comparison lt --version 2.3.2~ynh1 This example will check if the installed version is lower than (lt) the version 2.3.2~ynh1 -

+**Example**: `ynh_compare_current_package_version --comparison lt --version 2.3.2~ynh1 This example will check if the installed version is lower than (lt) the version 2.3.2~ynh1` -

- Details: -

- 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

Return 0 if the evaluation is true. 1 if false.

Requires YunoHost version 3.8.0 or higher.

-

-

-

- Dude, show me the code ! -

- -
-
- -
- - +**Details**: +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

Return 0 if the evaluation is true. 1 if false.

Requires YunoHost version 3.8.0 or higher.

+ - \ No newline at end of file