diff --git a/pages/06.contribute/10.packaging_apps/10.manifest/10.appresources/packaging_app_manifest_resources.md b/pages/06.contribute/10.packaging_apps/10.manifest/10.appresources/packaging_app_manifest_resources.md index a333ad00..9d772a92 100644 --- a/pages/06.contribute/10.packaging_apps/10.manifest/10.appresources/packaging_app_manifest_resources.md +++ b/pages/06.contribute/10.packaging_apps/10.manifest/10.appresources/packaging_app_manifest_resources.md @@ -7,7 +7,7 @@ routes: default: '/packaging_apps_resources' --- -Doc auto-generated by [this script](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/doc/generate_resource_doc.py) on 20/05/2024 (YunoHost version 11.2.12) +Doc auto-generated by [this script](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/doc/generate_resource_doc.py) on 24/06/2024 (YunoHost version 11.2.17) --- diff --git a/pages/06.contribute/10.packaging_apps/20.scripts/10.helpers/packaging_app_scripts_helpers.md b/pages/06.contribute/10.packaging_apps/20.scripts/10.helpers/packaging_app_scripts_helpers.md index 434d6dfe..e1e94924 100644 --- a/pages/06.contribute/10.packaging_apps/20.scripts/10.helpers/packaging_app_scripts_helpers.md +++ b/pages/06.contribute/10.packaging_apps/20.scripts/10.helpers/packaging_app_scripts_helpers.md @@ -1,5 +1,5 @@ --- -title: App helpers +title: App helpers (v2) template: docs taxonomy: category: docs @@ -7,996 +7,106 @@ routes: default: '/packaging_apps_helpers' --- -Doc auto-generated by [this script](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/doc/generate_helper_doc.py) on 20/05/2024 (YunoHost version 11.2.12) +Doc auto-generated by [this script](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/doc/generate_helper_doc.py) on 24/06/2024 (YunoHost version 11.2.17) -## APPS -### ynh_install_apps -[details summary="Install others YunoHost apps" class="helper-card-subtitle text-muted"] +## Sources -**Usage**: `ynh_install_apps --apps="appfoo?domain=domain.foo&path=/foo appbar?domain=domain.bar&path=/bar&admin=USER&language=fr&is_public=1&pass?word=pass&port=666"` +

This is coupled to the 'sources' resource in the manifest.toml

-**Arguments**: -- `-a`, `--apps=`: apps to install - -**Details**: -Requires YunoHost version *.*.* or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/apps#L9) -[/details] - ---- - -### ynh_remove_apps -[details summary="Remove other YunoHost apps" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_remove_apps` - -**Details**: -Other YunoHost apps will be removed only if no other apps need them. - -Requires YunoHost version *.*.* or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/apps#L65) -[/details] - ---- - -### ynh_spawn_app_shell -[details summary="Spawn a Bash shell with the app environment loaded" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_spawn_app_shell --app="app" - | arg: -a, --app= - the app ID` - -**Examples**: - - -- ` ynh_spawn_app_shell --app="APP" <<< 'echo "$USER"'` - - - -- ` ynh_spawn_app_shell --app="APP" < /tmp/some_script.bash` - -**Details**: -Requires YunoHost version 11.0.* or higher, and that the app relies on packaging v2 or higher. -The spawned shell will have environment variables loaded and environment files sourced -from the app's service configuration file (defaults to $app.service, overridable by the packager with `service` setting). -If the app relies on a specific PHP version, then `php` will be aliased that version. The PHP command will also be appended with the `phpflags` settings. +### SOURCES + +#### ynh_setup_source +
Download, check integrity, uncompress and patch the source from app.src -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/apps#L128) -[/details] - ---- - - -## APT - -### ynh_package_is_installed -[details summary="Check either a package is installed or not" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_package_is_installed --package=name` +**Usage**: `ynh_setup_source --dest_dir=dest_dir [--source_id=source_id] [--keep="file1 file2"] [--full_replace]` **Arguments**: -- `-p`, `--package=`: the package name to check - -**Returns**: 0 if the package is installed, 1 else. - -**Example**: `ynh_package_is_installed --package=yunohost && echo "installed"` +- `-d`, `--dest_dir=`: Directory where to setup sources +- `-s`, `--source_id=`: Name of the source, defaults to `main` (when the sources resource exists in manifest.toml) or (legacy) `app` otherwise +- `-k`, `--keep=`: Space-separated list of files/folders that will be backup/restored in $dest_dir, such as a config file you don't want to overwrite. For example 'conf.json secrets.json logs' (no trailing `/` for folders) +- `-r`, `--full_replace=`: Remove previous sources before installing new sources (can be 1 or 0, default to 0) **Details**: -Requires YunoHost version 2.2.4 or higher. +##### New 'sources' resources +(See also the resources documentation which may be more complete?) -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/apt#L53) -[/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. - -**Details**: -This helper can be used both in a system backup hook, and in an app backup script - -`ynh_backup` writes `src_path` and the relative `dest_path` into a CSV file, and it -creates the parent destination directory - -If `dest_path` is ended by a slash it complete this path with the basename of `src_path`. - -Example in the context of a wordpress app : -``` -ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" -# => This line will be added into CSV file -# "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/etc/nginx/conf.d/$domain.d/$app.conf" - -ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf/nginx.conf" -# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/nginx.conf" - -ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf/" -# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/$app.conf" - -ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf" -# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf" - -#Deprecated usages (maintained for retro-compatibility) -ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "${backup_dir}/conf/nginx.conf" -# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/nginx.conf" - -ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "/conf/" -# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/$app.conf" +This helper will read infos from the 'sources' resources in the manifest.toml of the app +and expect a structure like: +```toml +[resources.sources] + [resources.sources.main] + url = "https://some.address.to/download/the/app/archive" + sha256 = "0123456789abcdef" # The sha256 sum of the asset obtained from the URL ``` -How to use `--is_big`: +##### Optional flags -`--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. +```text +format = "tar.gz"/xz/bz2 # automatically guessed from the extension of the URL, but can be set explicitly. Will use `tar` to extract + "zip" # automatically guessed from the extension of the URL, but can be set explicitly. Will use `unzip` to extract + "docker" # useful to extract files from an already-built docker image (instead of rebuilding them locally). Will use `docker-image-extract` to extract + "whatever" # an arbitrary value, not really meaningful except to imply that the file won't be extracted -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 ! +in_subdir = true # default, there's an intermediate subdir in the archive before accessing the actual files + false # sources are directly in the archive root + n # (special cases) an integer representing a number of subdirs levels to get rid of -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. +extract = true # default if file is indeed an archive such as .zip, .tar.gz, .tar.bz2, ... + = false # default if file 'format' is not set and the file is not to be extracted because it is not an archive but a script or binary or whatever asset. + # in which case the file will only be `mv`ed to the location possibly renamed using the `rename` value -Requires YunoHost version 2.4.0 or higher. -Requires YunoHost version 3.5.0 or higher for the argument `--not_mandatory` +rename = "whatever_your_want" # to be used for convenience when `extract` is false and the default name of the file is not practical +platform = "linux/amd64" # (defaults to "linux/$YNH_ARCH") to be used in conjonction with `format = "docker"` to specify which architecture to extract for +``` +You may also define assets url and checksum per-architectures such as: +```toml +[resources.sources] + [resources.sources.main] + amd64.url = "https://some.address.to/download/the/app/archive/when/amd64" + amd64.sha256 = "0123456789abcdef" + armhf.url = "https://some.address.to/download/the/app/archive/when/armhf" + armhf.sha256 = "fedcba9876543210" +``` -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/backup#L64) -[/details] +In which case `ynh_setup_source --dest_dir="$install_dir"` will automatically pick the appropriate source depending on the arch ---- - -### 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/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/backup#L179) -[/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 -o "/etc/nginx/conf.d/$domain.d/$app.conf"` - - - -- `You can also use relative paths:` - - - -- ` ynh_restore_file -o "conf/nginx.conf"` - - - -**Details**: -Use the registered path in backup_list by ynh_backup to restore the file at the right place. - -If `DEST_PATH` already exists and is lighter than 500 Mo, a backup will be made in -`/var/cache/yunohost/appconfbackup/`. Otherwise, the existing file is removed. - -if `apps/$app/etc/nginx/conf.d/$domain.d/$app.conf` exists, restore it into -`/etc/nginx/conf.d/$domain.d/$app.conf` -if no, search for a match in the csv (eg: conf/nginx.conf) and restore it into -`/etc/nginx/conf.d/$domain.d/$app.conf` - -Requires YunoHost version 2.6.4 or higher. -Requires YunoHost version 3.5.0 or higher for the argument --not_mandatory - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/backup#L238) -[/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 +The helper will: +- Download the specific URL if there is no local archive +- Check the integrity with the specific sha256 sum +- Uncompress the archive to `$dest_dir`. + - If `in_subdir` is true, the first level directory of the archive will be removed. + - If `in_subdir` is a numeric value, the N first level directories will be removed. +- Patches named `sources/patches/${src_id}-*.patch` will be applied to `$dest_dir` +- Extra files in `sources/extra_files/$src_id` will be copied to dest_dir Requires YunoHost version 2.6.4 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/backup#L306) -[/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/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/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/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/backup#L397) -[/details] - ---- - - -## CONFIG - - -## FAIL2BAN - -### ynh_add_fail2ban_config -[details summary="Create a dedicated fail2ban config (jail and filter conf files)" class="helper-card-subtitle text-muted"] - -**Usage**: `1: ynh_add_fail2ban_config --logpath=log_file --failregex=filter [--max_retry=max_retry] [--ports=ports] -2: ynh_add_fail2ban_config --use_template` - -**Arguments**: -- `-l`, `--logpath=`: Log file to be checked by fail2ban -- `-r`, `--failregex=`: Failregex to be looked for by fail2ban -- `-m`, `--max_retry=`: Maximum number of retries allowed before banning IP address - default: 3 -- `-p`, `--ports=`: Ports blocked for a banned IP address - default: http,https -- `-t`, `--use_template`: Use this helper in template mode - -**Details**: -This will use a template in `../conf/f2b_jail.conf` and `../conf/f2b_filter.conf` -See the documentation of `ynh_add_config` for a description of the template -format and how placeholders are replaced with actual variables. - -Generally your template will look like that by example (for synapse): -``` -f2b_jail.conf: - [__APP__] - enabled = true - port = http,https - filter = __APP__ - logpath = /var/log/__APP__/logfile.log - maxretry = 3 -``` -``` -f2b_filter.conf: - [INCLUDES] - before = common.conf - [Definition] - -# Part of regex definition (just used to make more easy to make the global regex) - __synapse_start_line = .? \- synapse\..+ \- - -# Regex definition. - failregex = ^%(__synapse_start_line)s INFO \- POST\-(\d+)\- \- \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 - -To validate your regex you can test with this command: -``` -fail2ban-regex /var/log/YOUR_LOG_FILE_PATH /etc/fail2ban/filter.d/YOUR_APP.conf -``` - -Requires YunoHost version 4.1.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/fail2ban#L60) -[/details] - ---- - -### ynh_remove_fail2ban_config -[details summary="Remove the dedicated fail2ban config (jail and filter conf files)" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_remove_fail2ban_config` - -**Details**: -Requires YunoHost version 3.5.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/fail2ban#L132) -[/details] - ---- - - -## GETOPTS - - -## GO - -### ynh_use_go -[details summary="Load the version of Go for an app, and set variables." class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_use_go` - -**Details**: -ynh_use_go has to be used in any app scripts before using Go for the first time. -This helper will provide alias and variables to use in your scripts. - -To use gem or Go, use the alias `ynh_gem` and `ynh_go` -Those alias will use the correct version installed for the app -For example: use `ynh_gem install` instead of `gem install` - -With `sudo` or `ynh_exec_as`, use instead the fallback variables `$ynh_gem` and `$ynh_go` -And propagate $PATH to sudo with $ynh_go_load_path -Exemple: `ynh_exec_as $app $ynh_go_load_path $ynh_gem install` - -$PATH contains the path of the requested version of Go. -However, $PATH is duplicated into $go_path to outlast any manipulation of $PATH -You can use the variable `$ynh_go_load_path` to quickly load your Go version - in $PATH for an usage into a separate script. -Exemple: `$ynh_go_load_path $install_dir/script_that_use_gem.sh` - -Finally, to start a Go service with the correct version, 2 solutions - Either the app is dependent of Go or gem, but does not called it directly. - In such situation, you need to load PATH - `Environment="__YNH_GO_LOAD_PATH__"` - `ExecStart=__INSTALL_DIR__/my_app` - You will replace __YNH_GO_LOAD_PATH__ with $ynh_go_load_path - -Or Go start the app directly, then you don't need to load the PATH variable - `ExecStart=__YNH_GO__ my_app run` - You will replace __YNH_GO__ with $ynh_go - -one other variable is also available - - $go_path: The absolute path to Go binaries for the chosen version. - -Requires YunoHost version 3.2.2 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/go#L54) -[/details] - ---- - -### ynh_install_go -[details summary="Install a specific version of Go" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_install_go --go_version=go_version` - -**Arguments**: -- `-v`, `--go_version=`: Version of go to install. - -**Details**: -ynh_install_go will install the version of Go provided as argument by using goenv. - -This helper creates a /etc/profile.d/goenv.sh that configures PATH environment for goenv -for every LOGIN user, hence your user must have a defined shell (as opposed to /usr/sbin/nologin) - -Don't forget to execute go-dependent command in a login environment -(e.g. sudo --login option) -When not possible (e.g. in systemd service definition), please use direct path -to goenv shims (e.g. $goenv_ROOT/shims/bundle) - -Requires YunoHost version 3.2.2 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/go#L96) -[/details] - ---- - -### ynh_remove_go -[details summary="Remove the version of Go used by the app." class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_remove_go` - -**Details**: -This helper will also cleanup Go versions - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/go#L191) -[/details] - ---- - -### ynh_cleanup_go -[details summary="Remove no more needed versions of Go used by the app." class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_cleanup_go` - -**Details**: -This helper will check what Go version are no more required, -and uninstall them -If no app uses Go, goenv will be also removed. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/go#L214) -[/details] - ---- - - -## HARDWARE - - -## 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]` - -**Arguments**: -- `-m`, `--message=`: Message to display -- `-c`, `--ret_code=`: Exit code to exit with - -**Details**: -Requires YunoHost version 2.4.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/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"` - -**Arguments**: -- `-m`, `--message=`: Message to display - -**Details**: -Requires YunoHost version 3.2.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/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"` - -**Arguments**: -- `-m`, `--message=`: The text to print - -**Details**: -Requires YunoHost version 3.2.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/logging#L56) -[/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"` - -**Arguments**: -- `-m`, `--message=`: The text to print - -**Details**: -Requires YunoHost version 3.2.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/logging#L73) -[/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 and args` - -**Arguments**: -- `command`: command to execute - -**Details**: -Note that you should NOT quote the command but only prefix it with ynh_exec_err - -Requires YunoHost version 3.2.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/logging#L92) -[/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 and args` - -**Arguments**: -- `command`: command to execute - -**Details**: -Note that you should NOT quote the command but only prefix it with ynh_exec_warn - -Requires YunoHost version 3.2.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/logging#L113) -[/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 and args` - -**Arguments**: -- `command`: command to execute - -**Details**: -Note that you should NOT quote the command but only prefix it with ynh_exec_warn - -Requires YunoHost version 3.2.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/logging#L134) -[/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 and args` - -**Arguments**: -- `command`: command to execute - -**Details**: -Note that you should NOT quote the command but only prefix it with ynh_exec_warn - -Requires YunoHost version 3.2.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/logging#L155) -[/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_quiet your command and args` - -**Arguments**: -- `command`: command to execute - -**Details**: -Note that you should NOT quote the command but only prefix it with ynh_exec_quiet - -Requires YunoHost version 3.2.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/logging#L176) -[/details] - ---- - -### ynh_exec_and_print_stderr_only_if_error -[details summary="Execute a command and redirect stderr in /dev/null. Print stderr on error." class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_exec_and_print_stderr_only_if_error your command and args` - -**Arguments**: -- `command`: command to execute - -**Details**: -Note that you should NOT quote the command but only prefix it with ynh_exec_and_print_stderr_only_if_error - -Requires YunoHost version 11.2 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/logging#L197) -[/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]` - -**Arguments**: -- `-m`, `--message=`: The text to print -- `-w`, `--weight=`: The weight for this progression. This value is 1 by default. Use a bigger value for a longer part of the script. -- `-t`, `--time`: Print the execution time since the last call to this helper. Especially usefull to define weights. The execution time is given for the duration since the previous call. So the weight should be applied to this previous call. -- `-l`, `--last`: Use for the last call of the helper, to fill the progression bar. - -**Details**: -Requires YunoHost version 3.5.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/logging#L257) -[/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"] - -**Usage**: `ynh_return somedata` - -**Details**: -Requires YunoHost version 3.6.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/logging#L345) -[/details] - ---- - - -## 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] [--specific_user=user/group]` - -**Arguments**: -- `-l`, `--logfile=`: absolute path of logfile -- `-u`, `--specific_user=`: run logrotate as the specified user and group. If not specified logrotate is runned as root. - -**Details**: -If no `--logfile` is provided, `/var/log/$app` will be used as default. -`logfile` can point to a directory or a file. - -Requires YunoHost version 2.6.4 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/logrotate#L15) -[/details] - ---- - -### ynh_remove_logrotate -[details summary="Remove the app's logrotate config." class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_remove_logrotate` - -**Details**: -Requires YunoHost version 2.6.4 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/logrotate#L99) -[/details] - ---- - - -## MULTIMEDIA - -### ynh_multimedia_build_main_dir -[details summary="Initialize the multimedia directory system" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_multimedia_build_main_dir` - -**Details**: -Requires YunoHost version 4.2 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/multimedia#L11) -[/details] - ---- - -### ynh_multimedia_addfolder -[details summary="Add a directory in yunohost.multimedia" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_multimedia_addfolder --source_dir="source_dir" --dest_dir="dest_dir"` - -**Arguments**: -- `-s`, `--source_dir=`: Source directory - The real directory which contains your medias. -- `-d`, `--dest_dir=`: Destination directory - The name and the place of the symbolic link, relative to "/home/yunohost.multimedia" - -**Details**: -This "directory" will be a symbolic link to a existing directory. - -Requires YunoHost version 4.2 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/multimedia#L64) -[/details] - ---- - -### ynh_multimedia_addaccess -[details summary="Allow an user to have an write authorisation in multimedia directories" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_multimedia_addaccess user_name` - -**Arguments**: -- `-u`, `--user_name=`: The name of the user which gain this access. - -**Details**: -Requires YunoHost version 4.2 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/multimedia#L93) -[/details] - ---- - - -## 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]` - -**Arguments**: -- `-u`, `--user=`: the user name to connect as -- `-p`, `--password=`: the user password -- `-d`, `--database=`: the database to connect to - -**Examples**: - - -- ` ynh_mysql_connect_as --user="user" --password="pass" <<< "UPDATE ...;"` - - - -- ` ynh_mysql_connect_as --user="user" --password="pass" < /path/to/file.sql` +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/sources#L67) +
+--- -**Details**: -Requires YunoHost version 2.2.4 or higher. +## App Technologies +

These allow to install specific version of the technology required to run some apps

-[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/mysql#L15) -[/details] + ---- +### NODEJS + +#### ynh_use_nodejs -### 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]` - -**Arguments**: -- `-s`, `--sql=`: the SQL command to execute -- `-d`, `--database=`: the database to connect to - -**Details**: -Requires YunoHost version 2.2.4 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/mysql#L36) -[/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]` - -**Arguments**: -- `-f`, `--file=`: the file containing SQL commands -- `-d`, `--database=`: the database to connect to - -**Details**: -Requires YunoHost version 2.2.4 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/mysql#L60) -[/details] - ---- - -### ynh_mysql_dump_db -[details summary="Dump a database" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_mysql_dump_db --database=database` - -**Arguments**: -- `-d`, `--database=`: the database name to dump - -**Returns**: The mysqldump output - -**Example**: `ynh_mysql_dump_db --database=roundcube > ./dump.sql` - -**Details**: -Requires YunoHost version 2.2.4 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/mysql#L128) -[/details] - ---- - - -## NETWORK - -### ynh_validate_ip4 -[details summary="Validate an IPv4 address" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_validate_ip4 --ip_address=ip_address` - -**Arguments**: -- `-i`, `--ip_address=`: the ipv4 address to check - -**Returns**: 0 for valid ipv4 addresses, 1 otherwise - -**Example**: `ynh_validate_ip4 111.222.333.444` - -**Details**: -Requires YunoHost version 2.2.4 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/network#L103) -[/details] - ---- - -### ynh_validate_ip6 -[details summary="Validate an IPv6 address" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_validate_ip6 --ip_address=ip_address` - -**Arguments**: -- `-i`, `--ip_address=`: the ipv6 address to check - -**Returns**: 0 for valid ipv6 addresses, 1 otherwise - -**Example**: `ynh_validate_ip6 2000:dead:beef::1` - -**Details**: -Requires YunoHost version 2.2.4 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/network#L123) -[/details] - ---- - - -## NGINX - -### ynh_add_nginx_config -[details summary="Create a dedicated nginx config" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_add_nginx_config` - -**Details**: -This will use a template in `../conf/nginx.conf` -See the documentation of `ynh_add_config` for a description of the template -format and how placeholders are replaced with actual variables. - -Additionally, ynh_add_nginx_config will replace: -- `#sub_path_only` by empty string if `path_url` is not `'/'` -- `#root_path_only` by empty string if `path_url` *is* `'/'` - -This allows to enable/disable specific behaviors dependenging on the install -location - -Requires YunoHost version 4.1.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/nginx#L19) -[/details] - ---- - -### ynh_remove_nginx_config -[details summary="Remove the dedicated nginx config" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_remove_nginx_config` - -**Details**: -Requires YunoHost version 2.7.2 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/nginx#L41) -[/details] - ---- - -### ynh_change_url_nginx_config -[details summary="Regen the nginx config in a change url context" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_change_url_nginx_config` - -**Details**: -Requires YunoHost version 11.1.9 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/nginx#L52) -[/details] - ---- - - -## NODEJS - -### ynh_use_nodejs -[details summary="Load the version of node for an app, and set variables." class="helper-card-subtitle text-muted"] +
Load the version of node for an app, and set variables. **Usage**: `ynh_use_nodejs` @@ -1041,18 +151,17 @@ You will replace __YNH_NODE__ with $ynh_node Requires YunoHost version 2.7.12 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/nodejs#L52) -[/details] +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/nodejs#L52) +
+ +#### ynh_install_nodejs ---- - -### ynh_install_nodejs -[details summary="Install a specific version of nodejs" class="helper-card-subtitle text-muted"] +
Install a specific version of nodejs **Usage**: `ynh_install_nodejs --nodejs_version=nodejs_version` **Arguments**: -- `-n`, `--nodejs_version=`: Version of node to install. When possible, your should prefer to use major version number (e.g. 8 instead of 8.10.0). The crontab will then handle the update of minor versions when needed. +- `-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). **Details**: ynh_install_nodejs will install the version of node provided as argument by using n. @@ -1065,13 +174,12 @@ Refer to `ynh_use_nodejs` for more information about available commands and vari Requires YunoHost version 2.7.12 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/nodejs#L94) -[/details] +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/nodejs#L94) +
+ +#### ynh_remove_nodejs ---- - -### ynh_remove_nodejs -[details summary="Remove the version of node used by the app." class="helper-card-subtitle text-muted"] +
Remove the version of node used by the app. **Usage**: `ynh_remove_nodejs` @@ -1083,40 +191,844 @@ This helper will check if another app uses the same version of node. Requires YunoHost version 2.7.12 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/nodejs#L167) -[/details] - +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/nodejs#L164) +
+ --- + +### RUBY + +#### ynh_use_ruby -## PERMISSION +
Load the version of Ruby for an app, and set variables. -### 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` - -**Arguments**: -- `-p`, `--permission=`: the permission to check -- `-u`, `--user=`: the user seek in the permission - -**Example**: `ynh_permission_has_user --permission=main --user=visitors` +**Usage**: `ynh_use_ruby` **Details**: -Requires YunoHost version 3.7.1 or higher. +ynh_use_ruby has to be used in any app scripts before using Ruby for the first time. +This helper will provide alias and variables to use in your scripts. + +To use gem or Ruby, use the alias `ynh_gem` and `ynh_ruby` +Those alias will use the correct version installed for the app +For example: use `ynh_gem install` instead of `gem install` + +With `sudo` or `ynh_exec_as`, use instead the fallback variables `$ynh_gem` and `$ynh_ruby` +And propagate $PATH to sudo with $ynh_ruby_load_path +Exemple: `ynh_exec_as $app $ynh_ruby_load_path $ynh_gem install` + +$PATH contains the path of the requested version of Ruby. +However, $PATH is duplicated into $ruby_path to outlast any manipulation of $PATH +You can use the variable `$ynh_ruby_load_path` to quickly load your Ruby version + in $PATH for an usage into a separate script. +Exemple: $ynh_ruby_load_path $final_path/script_that_use_gem.sh` + +Finally, to start a Ruby service with the correct version, 2 solutions + Either the app is dependent of Ruby or gem, but does not called it directly. + In such situation, you need to load PATH + `Environment="__YNH_RUBY_LOAD_PATH__"` + `ExecStart=__FINALPATH__/my_app` + You will replace __YNH_RUBY_LOAD_PATH__ with $ynh_ruby_load_path + +Or Ruby start the app directly, then you don't need to load the PATH variable + `ExecStart=__YNH_RUBY__ my_app run` + You will replace __YNH_RUBY__ with $ynh_ruby + +one other variable is also available + - $ruby_path: The absolute path to Ruby binaries for the chosen version. + +Requires YunoHost version 3.2.2 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/permission#L339) -[/details] +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/ruby#L53) +
+ +#### ynh_install_ruby +
Install a specific version of Ruby + +**Usage**: `ynh_install_ruby --ruby_version=ruby_version` + +**Arguments**: +- `-v`, `--ruby_version=`: Version of ruby to install. + +**Details**: +ynh_install_ruby will install the version of Ruby provided as argument by using rbenv. + +This helper creates a /etc/profile.d/rbenv.sh that configures PATH environment for rbenv +for every LOGIN user, hence your user must have a defined shell (as opposed to /usr/sbin/nologin) + +Don't forget to execute ruby-dependent command in a login environment +(e.g. sudo --login option) +When not possible (e.g. in systemd service definition), please use direct path +to rbenv shims (e.g. $RBENV_ROOT/shims/bundle) + +Requires YunoHost version 3.2.2 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/ruby#L98) +
+ +#### ynh_remove_ruby + +
Remove the version of Ruby used by the app. + +**Usage**: `ynh_remove_ruby` + +**Details**: +This helper will also cleanup Ruby versions + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/ruby#L240) +
+ +#### ynh_cleanup_ruby + +
Remove no more needed versions of Ruby used by the app. + +**Usage**: `ynh_cleanup_ruby` + +**Details**: +This helper will check what Ruby version are no more required, +and uninstall them +If no app uses Ruby, rbenv will be also removed. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/ruby#L265) +
+ --- + + +### GO + +#### ynh_use_go + +
Load the version of Go for an app, and set variables. + +**Usage**: `ynh_use_go` + +**Details**: +ynh_use_go has to be used in any app scripts before using Go for the first time. +This helper will provide alias and variables to use in your scripts. + +To use gem or Go, use the alias `ynh_gem` and `ynh_go` +Those alias will use the correct version installed for the app +For example: use `ynh_gem install` instead of `gem install` + +With `sudo` or `ynh_exec_as`, use instead the fallback variables `$ynh_gem` and `$ynh_go` +And propagate $PATH to sudo with $ynh_go_load_path +Exemple: `ynh_exec_as $app $ynh_go_load_path $ynh_gem install` + +$PATH contains the path of the requested version of Go. +However, $PATH is duplicated into $go_path to outlast any manipulation of $PATH +You can use the variable `$ynh_go_load_path` to quickly load your Go version + in $PATH for an usage into a separate script. +Exemple: `$ynh_go_load_path $install_dir/script_that_use_gem.sh` + +Finally, to start a Go service with the correct version, 2 solutions + Either the app is dependent of Go or gem, but does not called it directly. + In such situation, you need to load PATH + `Environment="__YNH_GO_LOAD_PATH__"` + `ExecStart=__INSTALL_DIR__/my_app` + You will replace __YNH_GO_LOAD_PATH__ with $ynh_go_load_path + +Or Go start the app directly, then you don't need to load the PATH variable + `ExecStart=__YNH_GO__ my_app run` + You will replace __YNH_GO__ with $ynh_go + +one other variable is also available + - $go_path: The absolute path to Go binaries for the chosen version. + +Requires YunoHost version 3.2.2 or higher. -## PHP +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/go#L54) +
+ +#### ynh_install_go -### ynh_add_fpm_config -[details summary="Create a dedicated PHP-FPM config" class="helper-card-subtitle text-muted"] +
Install a specific version of Go + +**Usage**: `ynh_install_go --go_version=go_version` + +**Arguments**: +- `-v`, `--go_version=`: Version of go to install. + +**Details**: +ynh_install_go will install the version of Go provided as argument by using goenv. + +This helper creates a /etc/profile.d/goenv.sh that configures PATH environment for goenv +for every LOGIN user, hence your user must have a defined shell (as opposed to /usr/sbin/nologin) + +Don't forget to execute go-dependent command in a login environment +(e.g. sudo --login option) +When not possible (e.g. in systemd service definition), please use direct path +to goenv shims (e.g. $goenv_ROOT/shims/bundle) + +Requires YunoHost version 3.2.2 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/go#L96) +
+ +#### ynh_remove_go + +
Remove the version of Go used by the app. + +**Usage**: `ynh_remove_go` + +**Details**: +This helper will also cleanup Go versions + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/go#L185) +
+ +#### ynh_cleanup_go + +
Remove no more needed versions of Go used by the app. + +**Usage**: `ynh_cleanup_go` + +**Details**: +This helper will check what Go version are no more required, +and uninstall them +If no app uses Go, goenv will be also removed. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/go#L208) +
+ +--- + + +### COMPOSER + +#### ynh_composer_exec + +
Execute a command with Composer + +**Usage**: `ynh_composer_exec [--phpversion=phpversion] [--workdir=$install_dir] --commands="commands"` + +**Arguments**: +- `-v`, `--phpversion`: PHP version to use with composer +- `-w`, `--workdir`: The directory from where the command will be executed. Default $install_dir or $final_path +- `-c`, `--commands`: Commands to execute. + +**Details**: +Requires YunoHost version 4.2 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/composer#L16) +
+ +#### ynh_install_composer + +
Install and initialize Composer in the given directory + +**Usage**: `ynh_install_composer [--phpversion=phpversion] [--workdir=$install_dir] [--install_args="--optimize-autoloader"] [--composerversion=composerversion]` + +**Arguments**: +- `-v`, `--phpversion`: PHP version to use with composer +- `-w`, `--workdir`: The directory from where the command will be executed. Default $install_dir. +- `-a`, `--install_args`: Additional arguments provided to the composer install. Argument --no-dev already include +- `-c`, `--composerversion`: Composer version to install + +**Details**: +Requires YunoHost version 4.2 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/composer#L48) +
+ +--- + + +## Databases + +

This is coupled to the 'database' resource in the manifest.toml - at least for mysql/postgresql. Mongodb/redis may have better integration in the future.

+ + + +### MYSQL + +#### ynh_mysql_connect_as + +
Open a connection as a user + +**Usage**: `ynh_mysql_connect_as --user=user --password=password [--database=database]` + +**Arguments**: +- `-u`, `--user=`: the user name to connect as +- `-p`, `--password=`: the user password +- `-d`, `--database=`: the database to connect to + +**Examples**: + + +- ` ynh_mysql_connect_as --user="user" --password="pass" <<< "UPDATE ...;"` + + + +- ` ynh_mysql_connect_as --user="user" --password="pass" < /path/to/file.sql` + + + +**Details**: +Requires YunoHost version 2.2.4 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/mysql#L15) +
+ +#### ynh_mysql_execute_as_root + +
Execute a command as root user + +**Usage**: `ynh_mysql_execute_as_root --sql=sql [--database=database]` + +**Arguments**: +- `-s`, `--sql=`: the SQL command to execute +- `-d`, `--database=`: the database to connect to + +**Details**: +Requires YunoHost version 2.2.4 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/mysql#L36) +
+ +#### ynh_mysql_execute_file_as_root + +
Execute a command from a file as root user + +**Usage**: `ynh_mysql_execute_file_as_root --file=file [--database=database]` + +**Arguments**: +- `-f`, `--file=`: the file containing SQL commands +- `-d`, `--database=`: the database to connect to + +**Details**: +Requires YunoHost version 2.2.4 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/mysql#L60) +
+ +#### ynh_mysql_dump_db + +
Dump a database + +**Usage**: `ynh_mysql_dump_db --database=database` + +**Arguments**: +- `-d`, `--database=`: the database name to dump + +**Returns**: The mysqldump output + +**Example**: `ynh_mysql_dump_db --database=roundcube > ./dump.sql` + +**Details**: +Requires YunoHost version 2.2.4 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/mysql#L128) +
+ +--- + + +### POSTGRESQL + +#### ynh_psql_connect_as + +
Open a connection as a user + +**Usage**: `ynh_psql_connect_as --user=user --password=password [--database=database]` + +**Arguments**: +- `-u`, `--user=`: the user name to connect as +- `-p`, `--password=`: the user password +- `-d`, `--database=`: the database to connect to + +**Examples**: + + +- ` ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;"` + + + +- ` ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql` + + + +**Details**: +Requires YunoHost version 3.5.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/postgresql#L18) +
+ +#### ynh_psql_execute_as_root + +
Execute a command as root user + +**Usage**: `ynh_psql_execute_as_root --sql=sql [--database=database]` + +**Arguments**: +- `-s`, `--sql=`: the SQL command to execute +- `-d`, `--database=`: the database to connect to + +**Details**: +Requires YunoHost version 3.5.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/postgresql#L39) +
+ +#### ynh_psql_execute_file_as_root + +
Execute a command from a file as root user + +**Usage**: `ynh_psql_execute_file_as_root --file=file [--database=database]` + +**Arguments**: +- `-f`, `--file=`: the file containing SQL commands +- `-d`, `--database=`: the database to connect to + +**Details**: +Requires YunoHost version 3.5.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/postgresql#L64) +
+ +#### ynh_psql_dump_db + +
Dump a database + +**Usage**: `ynh_psql_dump_db --database=database` + +**Arguments**: +- `-d`, `--database=`: the database name to dump + +**Returns**: the psqldump output + +**Example**: `ynh_psql_dump_db 'roundcube' > ./dump.sql` + +**Details**: +Requires YunoHost version 3.5.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/postgresql#L135) +
+ +#### ynh_psql_database_exists + +
Check if a psql database exists + +**Usage**: `ynh_psql_database_exists --database=database +| exit: Return 1 if the database doesn't exist, 0 otherwise` + +**Arguments**: +- `-d`, `--database=`: the database for which to check existence + +**Details**: +Requires YunoHost version 3.5.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/postgresql#L192) +
+ +--- + + +### MONGODB + +#### ynh_mongo_exec + +
Execute a mongo command + +**Usage**: `ynh_mongo_exec [--user=user] [--password=password] [--authenticationdatabase=authenticationdatabase] [--database=database] [--host=host] [--port=port] --command="command" [--eval]` + +**Arguments**: +- `-u`, `--user=`: The user name to connect as +- `-p`, `--password=`: The user password +- `-d`, `--authenticationdatabase=`: The authenticationdatabase to connect to +- `-d`, `--database=`: The database to connect to +- `-h`, `--host=`: The host to connect to +- `-P`, `--port=`: The port to connect to +- `-c`, `--command=`: The command to evaluate +- `-e`, `--eval`: Evaluate instead of execute the command. + +**Example**: `ynh_mongo_exec --command='db.getMongo().getDBNames().indexOf("wekan")' example: ynh_mongo_exec --command="db.getMongo().getDBNames().indexOf(\"wekan\")"` + +**Details**: + + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/mongodb#L19) +
+ +#### ynh_mongo_dump_db + +
Dump a database + +**Usage**: `ynh_mongo_dump_db --database=database` + +**Arguments**: +- `-d`, `--database=`: The database name to dump + +**Returns**: the mongodump output + +**Example**: `ynh_mongo_dump_db --database=wekan > ./dump.bson` + +**Details**: + + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/mongodb#L136) +
+ +#### ynh_mongo_database_exists + +
Check if a mongo database exists + +**Usage**: `ynh_mongo_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**: + + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/mongodb#L181) +
+ +#### ynh_mongo_restore_db + +
Restore a database + +**Usage**: `ynh_mongo_restore_db --database=database` + +**Arguments**: +- `-d`, `--database=`: The database name to restore + +**Example**: `ynh_mongo_restore_db --database=wekan < ./dump.bson` + +**Details**: + + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/mongodb#L205) +
+ +#### ynh_mongo_setup_db + +
Create a database, an user and its password. Then store the password in the app's config + +**Usage**: `ynh_mongo_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 "mongopwd" into the app settings. + + + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/mongodb#L248) +
+ +#### ynh_mongo_remove_db + +
Remove a database if it exists, and the associated user + +**Usage**: `ynh_mongo_remove_db --db_user=user --db_name=name` + +**Arguments**: +- `-u`, `--db_user=`: Owner of the database +- `-n`, `--db_name=`: Name of the database + +**Details**: + + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/mongodb#L276) +
+ +#### ynh_install_mongo + +
Install MongoDB and integrate MongoDB service in YunoHost + +**Usage**: `ynh_install_mongo [--mongo_version=mongo_version]` + +**Arguments**: +- `-m`, `--mongo_version=`: Version of MongoDB to install + +**Details**: + + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/mongodb#L301) +
+ +#### ynh_remove_mongo + +
Remove MongoDB +Only remove the MongoDB service integration in YunoHost for now +if MongoDB package as been removed + +**Usage**: `ynh_remove_mongo` + +**Details**: + + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/mongodb#L344) +
+ +--- + + +### REDIS + +#### ynh_redis_get_free_db + +
get the first available redis database + +**Usage**: `ynh_redis_get_free_db` + +**Returns**: the database number to use +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/redis#L7) +
+ +#### ynh_redis_remove_db + +
Create a master password and set up global settings +Please always call this script in install and restore scripts + +**Usage**: `ynh_redis_remove_db database` + +**Arguments**: +- `database`: the database to erase +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/redis#L36) +
+ +--- + + +## Configurations / Templating + + + + + +### TEMPLATING + +#### ynh_add_config + +
Create a dedicated config file from a template + +**Usage**: `ynh_add_config --template="template" --destination="destination"` + +**Arguments**: +- `-t`, `--template=`: Template config file to use +- `-d`, `--destination=`: Destination of the config file +- `-j`, `--jinja`: Use jinja template instead of the simple `__MY_VAR__` templating format + +**Examples**: + + +- `ynh_add_config --template=".env" --destination="$install_dir/.env" # (use the template file "conf/.env" from the app's package)` + + + +- `ynh_add_config --jinja --template="config.j2" --destination="$install_dir/config" # (use the template file "conf/config.j2" from the app's package)` + + + +**Details**: +The template can be by default the name of a file in the conf directory +of a YunoHost Package, a relative path or an absolute path. + +The helper will use the template `template` to generate a config file +`destination` by replacing the following keywords with global variables +that should be defined before calling this helper : +``` + __PATH__ by $path_url + __NAME__ by $app + __NAMETOCHANGE__ by $app + __USER__ by $app + __FINALPATH__ by $final_path + __PHPVERSION__ by $YNH_PHP_VERSION (packaging v1 only, packaging v2 uses phpversion setting implicitly set by apt resource) + __YNH_NODE_LOAD_PATH__ by $ynh_node_load_PATH +``` +And any dynamic variables that should be defined before calling this helper like: +``` + __DOMAIN__ by $domain + __APP__ by $app + __VAR_1__ by $var_1 + __VAR_2__ by $var_2 +``` + +##### When --jinja is enabled + +This option is meant for advanced use-cases where the "simple" templating +mode ain't enough because you need conditional blocks or loops. + +For a full documentation of jinja's syntax you can refer to: +https://jinja.palletsprojects.com/en/3.1.x/templates/ + +Note that in YunoHost context, all variables are from shell variables and therefore are strings + +##### Keeping track of manual changes by the admin + +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/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/templating#L56) +
+ +#### ynh_read_var_in_file + +
Get a value from heterogeneous file (yaml, json, php, python...) + +**Usage**: `ynh_read_var_in_file --file=PATH --key=KEY` + +**Arguments**: +- `-f`, `--file=`: the path to the file +- `-k`, `--key=`: the key to get +- `-a`, `--after=`: the line just before the key (in case of multiple lines with the name of the key in the file) + +**Details**: +This helpers match several var affectation use case in several languages +We don't use jq or equivalent to keep comments and blank space in files +This helpers work line by line, it is not able to work correctly +if you have several identical keys in your files + +Example of line this helpers can managed correctly +.yml + title: YunoHost documentation + email: 'yunohost@yunohost.org' +.json + "theme": "colib'ris", + "port": 8102 + "some_boolean": false, + "user": null +.ini + some_boolean = On + action = "Clear" + port = 20 +.php + $user= + user => 20 +.py + USER = 8102 + user = 'https://donate.local' + CUSTOM['user'] = 'YunoHost' + +Requires YunoHost version 4.3 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/templating#L222) +
+ +#### ynh_write_var_in_file + +
Set a value into heterogeneous file (yaml, json, php, python...) + +**Usage**: `ynh_write_var_in_file --file=PATH --key=KEY --value=VALUE` + +**Arguments**: +- `-f`, `--file=`: the path to the file +- `-k`, `--key=`: the key to set +- `-v`, `--value=`: the value to set +- `-a`, `--after=`: the line just before the key (in case of multiple lines with the name of the key in the file) + +**Details**: +Requires YunoHost version 4.3 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/templating#L300) +
+ +--- + + +### NGINX + +#### ynh_add_nginx_config + +
Create a dedicated nginx config + +**Usage**: `ynh_add_nginx_config` + +**Details**: +This will use a template in `../conf/nginx.conf` +See the documentation of `ynh_add_config` for a description of the template +format and how placeholders are replaced with actual variables. + +Additionally, ynh_add_nginx_config will replace: +- `#sub_path_only` by empty string if `path_url` is not `'/'` +- `#root_path_only` by empty string if `path_url` *is* `'/'` + +This allows to enable/disable specific behaviors dependenging on the install +location + +Requires YunoHost version 4.1.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/nginx#L19) +
+ +#### ynh_remove_nginx_config + +
Remove the dedicated nginx config + +**Usage**: `ynh_remove_nginx_config` + +**Details**: +Requires YunoHost version 2.7.2 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/nginx#L41) +
+ +#### ynh_change_url_nginx_config + +
Regen the nginx config in a change url context + +**Usage**: `ynh_change_url_nginx_config` + +**Details**: +Requires YunoHost version 11.1.9 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/nginx#L52) +
+ +--- + + +### PHP + +#### ynh_add_fpm_config + +
Create a dedicated PHP-FPM config **Usage**: `ynh_add_fpm_config` @@ -1181,13 +1093,12 @@ Set as 'high', the process manager will be set at 'static'. There will be always Requires YunoHost version 4.1.0 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/php#L70) -[/details] +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/php#L70) +
+ +#### ynh_remove_fpm_config ---- - -### ynh_remove_fpm_config -[details summary="Remove the dedicated PHP-FPM config" class="helper-card-subtitle text-muted"] +
Remove the dedicated PHP-FPM config **Usage**: `ynh_remove_fpm_config` @@ -1195,422 +1106,17 @@ Requires YunoHost version 4.1.0 or higher. Requires YunoHost version 2.7.2 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/php#L284) -[/details] - +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/php#L284) +
+ --- - -### ynh_composer_exec -[details summary="Execute a command with Composer" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_composer_exec [--phpversion=phpversion] [--workdir=$install_dir] --commands="commands"` - -**Arguments**: -- `-v`, `--phpversion`: PHP version to use with composer -- `-w`, `--workdir`: The directory from where the command will be executed. Default $install_dir or $final_path -- `-c`, `--commands`: Commands to execute. - -**Details**: -Requires YunoHost version 4.2 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/php#L517) -[/details] - ---- - -### ynh_install_composer -[details summary="Install and initialize Composer in the given directory" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_install_composer [--phpversion=phpversion] [--workdir=$install_dir] [--install_args="--optimize-autoloader"] [--composerversion=composerversion]` - -**Arguments**: -- `-v`, `--phpversion`: PHP version to use with composer -- `-w`, `--workdir`: The directory from where the command will be executed. Default $install_dir. -- `-a`, `--install_args`: Additional arguments provided to the composer install. Argument --no-dev already include -- `-c`, `--composerversion`: Composer version to install - -**Details**: -Requires YunoHost version 4.2 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/php#L549) -[/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**: -- `-u`, `--user=`: the user name to connect as -- `-p`, `--password=`: the user password -- `-d`, `--database=`: the database to connect to - -**Examples**: - - -- ` ynh_psql_connect_as 'user' 'pass' <<< "UPDATE ...;"` - - - -- ` ynh_psql_connect_as 'user' 'pass' < /path/to/file.sql` - -**Details**: -Requires YunoHost version 3.5.0 or higher. +### SYSTEMD + +#### ynh_add_systemd_config - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/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]` - -**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/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/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/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/postgresql#L64) -[/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/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/postgresql#L135) -[/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/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/postgresql#L192) -[/details] - ---- - - -## REDIS - -### ynh_redis_get_free_db -[details summary="get the first available redis database" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_redis_get_free_db` - -**Returns**: the database number to use -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/redis#L7) -[/details] - ---- - -### ynh_redis_remove_db -[details summary="Create a master password and set up global settings -Please always call this script in install and restore scripts" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_redis_remove_db database` - -**Arguments**: -- `database`: the database to erase -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/redis#L36) -[/details] - ---- - - -## RUBY - -### ynh_use_ruby -[details summary="Load the version of Ruby for an app, and set variables." class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_use_ruby` - -**Details**: -ynh_use_ruby has to be used in any app scripts before using Ruby for the first time. -This helper will provide alias and variables to use in your scripts. - -To use gem or Ruby, use the alias `ynh_gem` and `ynh_ruby` -Those alias will use the correct version installed for the app -For example: use `ynh_gem install` instead of `gem install` - -With `sudo` or `ynh_exec_as`, use instead the fallback variables `$ynh_gem` and `$ynh_ruby` -And propagate $PATH to sudo with $ynh_ruby_load_path -Exemple: `ynh_exec_as $app $ynh_ruby_load_path $ynh_gem install` - -$PATH contains the path of the requested version of Ruby. -However, $PATH is duplicated into $ruby_path to outlast any manipulation of $PATH -You can use the variable `$ynh_ruby_load_path` to quickly load your Ruby version - in $PATH for an usage into a separate script. -Exemple: $ynh_ruby_load_path $final_path/script_that_use_gem.sh` - -Finally, to start a Ruby service with the correct version, 2 solutions - Either the app is dependent of Ruby or gem, but does not called it directly. - In such situation, you need to load PATH - `Environment="__YNH_RUBY_LOAD_PATH__"` - `ExecStart=__FINALPATH__/my_app` - You will replace __YNH_RUBY_LOAD_PATH__ with $ynh_ruby_load_path - -Or Ruby start the app directly, then you don't need to load the PATH variable - `ExecStart=__YNH_RUBY__ my_app run` - You will replace __YNH_RUBY__ with $ynh_ruby - -one other variable is also available - - $ruby_path: The absolute path to Ruby binaries for the chosen version. - -Requires YunoHost version 3.2.2 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/ruby#L53) -[/details] - ---- - -### ynh_install_ruby -[details summary="Install a specific version of Ruby" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_install_ruby --ruby_version=ruby_version` - -**Arguments**: -- `-v`, `--ruby_version=`: Version of ruby to install. - -**Details**: -ynh_install_ruby will install the version of Ruby provided as argument by using rbenv. - -This helper creates a /etc/profile.d/rbenv.sh that configures PATH environment for rbenv -for every LOGIN user, hence your user must have a defined shell (as opposed to /usr/sbin/nologin) - -Don't forget to execute ruby-dependent command in a login environment -(e.g. sudo --login option) -When not possible (e.g. in systemd service definition), please use direct path -to rbenv shims (e.g. $RBENV_ROOT/shims/bundle) - -Requires YunoHost version 3.2.2 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/ruby#L98) -[/details] - ---- - -### ynh_remove_ruby -[details summary="Remove the version of Ruby used by the app." class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_remove_ruby` - -**Details**: -This helper will also cleanup Ruby versions - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/ruby#L240) -[/details] - ---- - -### ynh_cleanup_ruby -[details summary="Remove no more needed versions of Ruby used by the app." class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_cleanup_ruby` - -**Details**: -This helper will check what Ruby version are no more required, -and uninstall them -If no app uses Ruby, rbenv will be also removed. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/ruby#L265) -[/details] - ---- - - -## 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` - -**Arguments**: -- `-a`, `--app=`: the application id -- `-k`, `--key=`: the setting to get - -**Details**: -Requires YunoHost version 2.2.4 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/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` - -**Arguments**: -- `-a`, `--app=`: the application id -- `-k`, `--key=`: the setting name to set -- `-v`, `--value=`: the setting value to set - -**Details**: -Requires YunoHost version 2.2.4 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/setting#L36) -[/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` - -**Arguments**: -- `-a`, `--app=`: the application id -- `-k`, `--key=`: the setting to delete - -**Details**: -Requires YunoHost version 2.2.4 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/setting#L62) -[/details] - ---- - - -## STRING - -### ynh_string_random -[details summary="Generate a random string" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_string_random [--length=string_length]` - -**Arguments**: -- `-l`, `--length=`: the string length to generate (default: 24) -- `-f`, `--filter=`: the kind of characters accepted in the output (default: 'A-Za-z0-9') - -**Returns**: the generated string - -**Example**: `pwd=$(ynh_string_random --length=8)` - -**Details**: -Requires YunoHost version 2.2.4 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/string#L13) -[/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` - -**Arguments**: -- `-m`, `--match_string=`: String to be searched and replaced in the file -- `-r`, `--replace_string=`: String that will replace matches -- `-f`, `--target_file=`: File in which the string will be replaced. - -**Details**: -As this helper is based on sed command, regular expressions and references to -sub-expressions can be used (see sed manual page for more information) - -Requires YunoHost version 2.6.4 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/string#L40) -[/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` - -**Arguments**: -- `-m`, `--match_string=`: String to be searched and replaced in the file -- `-r`, `--replace_string=`: String that will replace matches -- `-t`, `--target_file=`: File in which the string will be replaced. - -**Details**: -This helper will use ynh_replace_string, but as you can use special -characters, you can't use some regular expressions and sub-expressions. - -Requires YunoHost version 2.7.7 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/string#L71) -[/details] - ---- - - -## SYSTEMD - -### ynh_add_systemd_config -[details summary="Create a dedicated systemd config" class="helper-card-subtitle text-muted"] +
Create a dedicated systemd config **Usage**: `ynh_add_systemd_config [--service=service] [--template=template]` @@ -1627,13 +1133,12 @@ format and how placeholders are replaced with actual variables. Requires YunoHost version 4.1.0 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/systemd#L15) -[/details] +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/systemd#L15) +
+ +#### ynh_remove_systemd_config ---- - -### ynh_remove_systemd_config -[details summary="Remove the dedicated systemd config" class="helper-card-subtitle text-muted"] +
Remove the dedicated systemd config **Usage**: `ynh_remove_systemd_config [--service=service]` @@ -1644,13 +1149,12 @@ Requires YunoHost version 4.1.0 or higher. Requires YunoHost version 2.7.2 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/systemd#L38) -[/details] +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/systemd#L38) +
+ +#### ynh_systemd_action ---- - -### 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"] +
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] ]` @@ -1666,186 +1170,143 @@ Requires YunoHost version 2.7.2 or higher. Requires YunoHost version 3.5.0 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/systemd#L67) -[/details] - +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/systemd#L67) +
+ --- + +### FAIL2BAN + +#### ynh_add_fail2ban_config -## USER +
Create a dedicated fail2ban config (jail and filter conf files) -### ynh_user_exists -[details summary="Check if a YunoHost user exists" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_user_exists --username=username` +**Usage**: `1: ynh_add_fail2ban_config --logpath=log_file --failregex=filter [--max_retry=max_retry] [--ports=ports] +2: ynh_add_fail2ban_config --use_template` **Arguments**: -- `-u`, `--username=`: the username to check - -**Returns**: 0 if the user exists, 1 otherwise. - -**Example**: `ynh_user_exists 'toto' || echo "User does not exist"` +- `-l`, `--logpath=`: Log file to be checked by fail2ban +- `-r`, `--failregex=`: Failregex to be looked for by fail2ban +- `-m`, `--max_retry=`: Maximum number of retries allowed before banning IP address - default: 3 +- `-p`, `--ports=`: Ports blocked for a banned IP address - default: http,https +- `-t`, `--use_template`: Use this helper in template mode **Details**: -Requires YunoHost version 2.2.4 or higher. +This will use a template in `../conf/f2b_jail.conf` and `../conf/f2b_filter.conf` +See the documentation of `ynh_add_config` for a description of the template +format and how placeholders are replaced with actual variables. + +Generally your template will look like that by example (for synapse): +``` +f2b_jail.conf: + [__APP__] + enabled = true + port = http,https + filter = __APP__ + logpath = /var/log/__APP__/logfile.log + maxretry = 3 +``` +``` +f2b_filter.conf: + [INCLUDES] + before = common.conf + [Definition] + +# Part of regex definition (just used to make more easy to make the global regex) + __synapse_start_line = .? \- synapse\..+ \- + +# Regex definition. + failregex = ^%(__synapse_start_line)s INFO \- POST\-(\d+)\- \- \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 + +To validate your regex you can test with this command: +``` +fail2ban-regex /var/log/YOUR_LOG_FILE_PATH /etc/fail2ban/filter.d/YOUR_APP.conf +``` + +Requires YunoHost version 4.1.0 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/user#L12) -[/details] +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/fail2ban#L58) +
+ +#### ynh_remove_fail2ban_config +
Remove the dedicated fail2ban config (jail and filter conf files) + +**Usage**: `ynh_remove_fail2ban_config` + +**Details**: +Requires YunoHost version 3.5.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/fail2ban#L130) +
+ --- + -### ynh_user_get_info -[details summary="Retrieve a YunoHost user information" class="helper-card-subtitle text-muted"] +### LOGROTATE + +#### ynh_use_logrotate -**Usage**: `ynh_user_get_info --username=username --key=key` +
Use logrotate to manage the logfile + +**Usage**: `ynh_use_logrotate [--logfile=/log/file] [--specific_user=user/group]` **Arguments**: -- `-u`, `--username=`: the username to retrieve info from -- `-k`, `--key=`: the key to retrieve - -**Returns**: the value associate to that key - -**Example**: `mail=$(ynh_user_get_info --username="toto" --key=mail)` +- `-l`, `--logfile=`: absolute path of logfile +- `-u`, `--specific_user=`: run logrotate as the specified user and group. If not specified logrotate is runned as root. **Details**: -Requires YunoHost version 2.2.4 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/user#L33) -[/details] - ---- - -### ynh_user_list -[details summary="Get the list of YunoHost users" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_user_list` - -**Returns**: one username per line as strings - -**Example**: `for u in $(ynh_user_list); do ... ; done` - -**Details**: -Requires YunoHost version 2.4.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/user#L53) -[/details] - ---- - -### ynh_exec_as -[details summary="Execute a command as another user" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_exec_as $USER COMMAND [ARG ...]` - -**Details**: -Requires YunoHost version 4.1.7 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/user#L187) -[/details] - ---- - - -## UTILS - -### 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] [--keep="file1 file2"] [--full_replace]` - -**Arguments**: -- `-d`, `--dest_dir=`: Directory where to setup sources -- `-s`, `--source_id=`: Name of the source, defaults to `main` (when the sources resource exists in manifest.toml) or (legacy) `app` otherwise -- `-k`, `--keep=`: Space-separated list of files/folders that will be backup/restored in $dest_dir, such as a config file you don't want to overwrite. For example 'conf.json secrets.json logs' (no trailing `/` for folders) -- `-r`, `--full_replace=`: Remove previous sources before installing new sources (can be 1 or 0, default to 0) - -**Details**: -#### New 'sources' resources - -(See also the resources documentation which may be more complete?) - -This helper will read infos from the 'sources' resources in the manifest.toml of the app -and expect a structure like: - -```toml -[resources.sources] - [resources.sources.main] - url = "https://some.address.to/download/the/app/archive" - sha256 = "0123456789abcdef" # The sha256 sum of the asset obtained from the URL -``` - -##### Optional flags - -```text -format = "tar.gz"/xz/bz2 # automatically guessed from the extension of the URL, but can be set explicitly. Will use `tar` to extract - "zip" # automatically guessed from the extension of the URL, but can be set explicitly. Will use `unzip` to extract - "docker" # useful to extract files from an already-built docker image (instead of rebuilding them locally). Will use `docker-image-extract` to extract - "whatever" # an arbitrary value, not really meaningful except to imply that the file won't be extracted - -in_subdir = true # default, there's an intermediate subdir in the archive before accessing the actual files - false # sources are directly in the archive root - n # (special cases) an integer representing a number of subdirs levels to get rid of - -extract = true # default if file is indeed an archive such as .zip, .tar.gz, .tar.bz2, ... - = false # default if file 'format' is not set and the file is not to be extracted because it is not an archive but a script or binary or whatever asset. - # in which case the file will only be `mv`ed to the location possibly renamed using the `rename` value - -rename = "whatever_your_want" # to be used for convenience when `extract` is false and the default name of the file is not practical -platform = "linux/amd64" # (defaults to "linux/$YNH_ARCH") to be used in conjonction with `format = "docker"` to specify which architecture to extract for -``` - -You may also define assets url and checksum per-architectures such as: -```toml -[resources.sources] - [resources.sources.main] - amd64.url = "https://some.address.to/download/the/app/archive/when/amd64" - amd64.sha256 = "0123456789abcdef" - armhf.url = "https://some.address.to/download/the/app/archive/when/armhf" - armhf.sha256 = "fedcba9876543210" -``` - -In which case ynh_setup_source --dest_dir="$install_dir" will automatically pick the appropriate source depending on the arch - - - -#### Legacy format '.src' - -This helper will read `conf/${source_id}.src`, download and install the sources. - -The src file need to contains: -``` -SOURCE_URL=Address to download the app archive -SOURCE_SUM=Sha256 sum -SOURCE_FORMAT=tar.gz -SOURCE_IN_SUBDIR=false -SOURCE_FILENAME=example.tar.gz -SOURCE_EXTRACT=(true|false) -SOURCE_PLATFORM=linux/arm64/v8 -``` - -The helper will: -- Download the specific URL if there is no local archive -- Check the integrity with the specific sha256 sum -- Uncompress the archive to `$dest_dir`. - - If `in_subdir` is true, the first level directory of the archive will be removed. - - If `in_subdir` is a numeric value, the N first level directories will be removed. -- Patches named `sources/patches/${src_id}-*.patch` will be applied to `$dest_dir` -- Extra files in `sources/extra_files/$src_id` will be copied to dest_dir +If no `--logfile` is provided, `/var/log/$app` will be used as default. +`logfile` can point to a directory or a file. Requires YunoHost version 2.6.4 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/utils#L156) -[/details] +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/logrotate#L15) +
+ +#### ynh_remove_logrotate +
Remove the app's logrotate config. + +**Usage**: `ynh_remove_logrotate` + +**Details**: +Requires YunoHost version 2.6.4 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/logrotate#L99) +
+ --- + -### 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"] +## Misc Tools + + + + + +### UTILS + +#### 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" ...` @@ -1865,136 +1326,12 @@ For multiple calls, cookies are persisted between each call for the same app Requires YunoHost version 2.6.4 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/utils#L406) -[/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"` - -**Arguments**: -- `-t`, `--template=`: Template config file to use -- `-d`, `--destination=`: Destination of the config file - -**Examples**: - +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/utils#L90) +
-- ` ynh_add_config --template=".env" --destination="$install_dir/.env" use the template file "../conf/.env"` - - - -- ` ynh_add_config --template="/etc/nginx/sites-available/default" --destination="etc/nginx/sites-available/mydomain.conf"` - - +#### ynh_secure_remove -**Details**: -The template can be by default the name of a file in the conf directory -of a YunoHost Package, a relative path or an absolute path. - -The helper will use the template `template` to generate a config file -`destination` by replacing the following keywords with global variables -that should be defined before calling this helper : -``` - __PATH__ by $path_url - __NAME__ by $app - __NAMETOCHANGE__ by $app - __USER__ by $app - __FINALPATH__ by $final_path - __PHPVERSION__ by $YNH_PHP_VERSION (packaging v1 only, packaging v2 uses phpversion setting implicitly set by apt resource) - __YNH_NODE_LOAD_PATH__ by $ynh_node_load_PATH -``` -And any dynamic variables that should be defined before calling this helper like: -``` - __DOMAIN__ by $domain - __APP__ by $app - __VAR_1__ by $var_1 - __VAR_2__ by $var_2 -``` - -The helper will verify the checksum and backup the destination file -if it's different before applying the new template. - -And it will calculate and store the destination file checksum -into the app settings when configuration is done. - -Requires YunoHost version 4.1.0 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/utils#L490) -[/details] - ---- - -### ynh_read_var_in_file -[details summary="Get a value from heterogeneous file (yaml, json, php, python...)" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_read_var_in_file --file=PATH --key=KEY` - -**Arguments**: -- `-f`, `--file=`: the path to the file -- `-k`, `--key=`: the key to get -- `-a`, `--after=`: the line just before the key (in case of multiple lines with the name of the key in the file) - -**Details**: -This helpers match several var affectation use case in several languages -We don't use jq or equivalent to keep comments and blank space in files -This helpers work line by line, it is not able to work correctly -if you have several identical keys in your files - -Example of line this helpers can managed correctly -.yml - title: YunoHost documentation - email: 'yunohost@yunohost.org' -.json - "theme": "colib'ris", - "port": 8102 - "some_boolean": false, - "user": null -.ini - some_boolean = On - action = "Clear" - port = 20 -.php - $user= - user => 20 -.py - USER = 8102 - user = 'https://donate.local' - CUSTOM['user'] = 'YunoHost' - -Requires YunoHost version 4.3 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/utils#L648) -[/details] - ---- - -### ynh_write_var_in_file -[details summary="Set a value into heterogeneous file (yaml, json, php, python...)" class="helper-card-subtitle text-muted"] - -**Usage**: `ynh_write_var_in_file --file=PATH --key=KEY --value=VALUE` - -**Arguments**: -- `-f`, `--file=`: the path to the file -- `-k`, `--key=`: the key to set -- `-v`, `--value=`: the value to set -- `-a`, `--after=`: the line just before the key (in case of multiple lines with the name of the key in the file) - -**Details**: -Requires YunoHost version 4.3 or higher. - - -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/utils#L726) -[/details] - ---- - -### ynh_secure_remove -[details summary="Remove a file or a directory securely" class="helper-card-subtitle text-muted"] +
Remove a file or a directory securely **Usage**: `ynh_secure_remove --file=path_to_remove` @@ -2005,19 +1342,18 @@ Requires YunoHost version 4.3 or higher. Requires YunoHost version 2.6.4 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/utils#L874) -[/details] +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/utils#L173) +
+ +#### ynh_read_manifest ---- +
Read the value of a key in a ynh manifest file -### 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"` +**Usage**: `ynh_read_manifest --manifest="manifest.json" --manifest_key="key"` **Arguments**: - `-m`, `--manifest=`: Path of the manifest to read -- `-k`, `--key=`: Name of the key to find +- `-k`, `--manifest_key=`: Name of the key to find **Returns**: the value associate to that key @@ -2025,13 +1361,12 @@ Requires YunoHost version 2.6.4 or higher. Requires YunoHost version 3.5.0 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/utils#L908) -[/details] +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/utils#L207) +
+ +#### ynh_app_upstream_version ---- - -### ynh_app_upstream_version -[details summary="Read the upstream version from the manifest or `$YNH_APP_MANIFEST_VERSION`" class="helper-card-subtitle text-muted"] +
Read the upstream version from the manifest or `$YNH_APP_MANIFEST_VERSION` **Usage**: `ynh_app_upstream_version [--manifest="manifest.json"]` @@ -2050,13 +1385,12 @@ For example, if the manifest contains `4.3-2~ynh3` the function will return `4.3 Requires YunoHost version 3.5.0 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/utils#L951) -[/details] +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/utils#L250) +
+ +#### ynh_check_app_version_changed ---- - -### 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"] +
Checks the app version to upgrade with the existing app version and returns: **Usage**: `ynh_check_app_version_changed` @@ -2069,13 +1403,12 @@ of it, when it's not needed Requires YunoHost version 3.5.0 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/utils#L1003) -[/details] +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/utils#L302) +
+ +#### ynh_compare_current_package_version ---- - -### ynh_compare_current_package_version -[details summary="Compare the current package version against another version given as an argument." class="helper-card-subtitle text-muted"] +
Compare the current package version against another version given as an argument. **Usage**: `ynh_compare_current_package_version --comparison (lt|le|eq|ne|ge|gt) --version ` @@ -2101,8 +1434,745 @@ fi Requires YunoHost version 3.8.0 or higher. -[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/d5e054fe80002862bd5966d61b20e9fafcf0578e/helpers/utils#L1033) -[/details] +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/utils#L332) +
+ +#### ynh_user_exists +
Check if a YunoHost user exists + +**Usage**: `ynh_user_exists --username=username` + +**Arguments**: +- `-u`, `--username=`: the username to check + +**Returns**: 0 if the user exists, 1 otherwise. + +**Example**: `ynh_user_exists 'toto' || echo "User does not exist"` + +**Details**: +Requires YunoHost version 2.2.4 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/utils#L414) +
+ +#### ynh_user_get_info + +
Retrieve a YunoHost user information + +**Usage**: `ynh_user_get_info --username=username --key=key` + +**Arguments**: +- `-u`, `--username=`: the username to retrieve info from +- `-k`, `--key=`: the key to retrieve + +**Returns**: the value associate to that key + +**Example**: `mail=$(ynh_user_get_info --username="toto" --key=mail)` + +**Details**: +Requires YunoHost version 2.2.4 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/utils#L435) +
+ +#### ynh_user_list + +
Get the list of YunoHost users + +**Usage**: `ynh_user_list` + +**Returns**: one username per line as strings + +**Example**: `for u in $(ynh_user_list); do ... ; done` + +**Details**: +Requires YunoHost version 2.4.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/utils#L455) +
+ --- + +### SETTING + +#### ynh_app_setting_get + +
Get an application setting + +**Usage**: `ynh_app_setting_get --app=app --key=key` + +**Arguments**: +- `-a`, `--app=`: the application id +- `-k`, `--key=`: the setting to get + +**Details**: +Requires YunoHost version 2.2.4 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/setting#L10) +
+ +#### ynh_app_setting_set + +
Set an application setting + +**Usage**: `ynh_app_setting_set --app=app --key=key --value=value` + +**Arguments**: +- `-a`, `--app=`: the application id +- `-k`, `--key=`: the setting name to set +- `-v`, `--value=`: the setting value to set + +**Details**: +Requires YunoHost version 2.2.4 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/setting#L36) +
+ +#### ynh_app_setting_set_default + +
Set an application setting but only if the "$key" variable ain't set yet + +**Usage**: `ynh_app_setting_set_default --app=app --key=key --value=value` + +**Arguments**: +- `-a`, `--app=`: the application id +- `-k`, `--key=`: the setting name to set +- `-v`, `--value=`: the default setting value to set + +**Details**: +Note that it doesn't just define the setting but ALSO define the $foobar variable + +Hence it's meant as a replacement for this legacy overly complex syntax: + +if [ -z "${foo:-}" ] +then + foo="bar" + ynh_app_setting_set --key="foo" --value="$foo" +fi + +Requires YunoHost version 11.1.16 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/setting#L73) +
+ +#### ynh_app_setting_delete + +
Delete an application setting + +**Usage**: `ynh_app_setting_delete --app=app --key=key` + +**Arguments**: +- `-a`, `--app=`: the application id +- `-k`, `--key=`: the setting to delete + +**Details**: +Requires YunoHost version 2.2.4 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/setting#L98) +
+ +--- + + +### STRING + +#### ynh_string_random + +
Generate a random string + +**Usage**: `ynh_string_random [--length=string_length]` + +**Arguments**: +- `-l`, `--length=`: the string length to generate (default: 24) +- `-f`, `--filter=`: the kind of characters accepted in the output (default: 'A-Za-z0-9') + +**Returns**: the generated string + +**Example**: `pwd=$(ynh_string_random --length=8)` + +**Details**: +Requires YunoHost version 2.2.4 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/string#L13) +
+ +#### ynh_replace_string + +
Substitute/replace a string (or expression) by another in a file + +**Usage**: `ynh_replace_string --match_string=match_string --replace_string=replace_string --target_file=target_file` + +**Arguments**: +- `-m`, `--match_string=`: String to be searched and replaced in the file +- `-r`, `--replace_string=`: String that will replace matches +- `-f`, `--target_file=`: File in which the string will be replaced. + +**Details**: +As this helper is based on sed command, regular expressions and references to +sub-expressions can be used (see sed manual page for more information) + +Requires YunoHost version 2.6.4 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/string#L40) +
+ +#### ynh_replace_special_string + +
Substitute/replace a special string by another in a file + +**Usage**: `ynh_replace_special_string --match_string=match_string --replace_string=replace_string --target_file=target_file` + +**Arguments**: +- `-m`, `--match_string=`: String to be searched and replaced in the file +- `-r`, `--replace_string=`: String that will replace matches +- `-t`, `--target_file=`: File in which the string will be replaced. + +**Details**: +This helper will use ynh_replace_string, but as you can use special +characters, you can't use some regular expressions and sub-expressions. + +Requires YunoHost version 2.7.7 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/string#L71) +
+ +--- + + +### BACKUP + +#### ynh_backup + +
Add a file or a directory to the list of paths to backup + +**Usage**: `ynh_backup --src_path=src_path [--dest_path=dest_path] [--is_big] [--not_mandatory]` + +**Arguments**: +- `-s`, `--src_path=`: file or directory to bind or symlink or copy. it shouldn't be in the backup dir. +- `-d`, `--dest_path=`: destination file or directory inside the backup dir +- `-b`, `--is_big`: Indicate data are big (mail, video, image ...) +- `-m`, `--not_mandatory`: Indicate that if the file is missing, the backup can ignore it. + +**Details**: +This helper can be used both in a system backup hook, and in an app backup script + +`ynh_backup` writes `src_path` and the relative `dest_path` into a CSV file, and it +creates the parent destination directory + +If `dest_path` is ended by a slash it complete this path with the basename of `src_path`. + +Example in the context of a wordpress app : +``` +ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" +# => This line will be added into CSV file +# "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/etc/nginx/conf.d/$domain.d/$app.conf" + +ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf/nginx.conf" +# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/nginx.conf" + +ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf/" +# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/$app.conf" + +ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "conf" +# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf" + +#Deprecated usages (maintained for retro-compatibility) +ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "${backup_dir}/conf/nginx.conf" +# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/nginx.conf" + +ynh_backup "/etc/nginx/conf.d/$domain.d/$app.conf" "/conf/" +# => "/etc/nginx/conf.d/$domain.d/$app.conf","apps/wordpress/conf/$app.conf" + +``` + +How to use `--is_big`: + +`--is_big` is used to specify that this part of the backup can be quite huge. +So, you don't want that your package does backup that part during ynh_backup_before_upgrade. +In the same way, an user may doesn't want to backup this big part of the app for +each of his backup. And so handle that part differently. + +As this part of your backup may not be done, your restore script has to handle it. +In your restore script, use `--not_mandatory` with `ynh_restore_file` +As well in your remove script, you should not remove those data ! Or an user may end up with +a failed upgrade restoring an app without data anymore ! + +To have the benefit of `--is_big` while doing a backup, you can whether set the environement +variable `BACKUP_CORE_ONLY` to 1 (`BACKUP_CORE_ONLY=1`) before the backup command. It will affect +only that backup command. +Or set the config `do_not_backup_data` to 1 into the `settings.yml` of the app. This will affect +all backups for this app until the setting is removed. + +Requires YunoHost version 2.4.0 or higher. +Requires YunoHost version 3.5.0 or higher for the argument `--not_mandatory` + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/backup#L64) +
+ +#### 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!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/backup#L179) +
+ +#### ynh_restore_file + +
Restore a file or a directory + +**Usage**: `ynh_restore_file --origin_path=origin_path [--dest_path=dest_path] [--not_mandatory]` + +**Arguments**: +- `-o`, `--origin_path=`: Path where was located the file or the directory before to be backuped or relative path to $YNH_CWD where it is located in the backup archive +- `-d`, `--dest_path=`: Path where restore the file or the dir. If unspecified, the destination will be `ORIGIN_PATH` or if the `ORIGIN_PATH` doesn't exist in the archive, the destination will be searched into `backup.csv` +- `-m`, `--not_mandatory`: Indicate that if the file is missing, the restore process can ignore it. + +**Examples**: + + +- ` ynh_restore_file -o "/etc/nginx/conf.d/$domain.d/$app.conf"` + + + +- `You can also use relative paths:` + + + +- ` ynh_restore_file -o "conf/nginx.conf"` + + + +**Details**: +Use the registered path in backup_list by ynh_backup to restore the file at the right place. + +If `DEST_PATH` already exists and is lighter than 500 Mo, a backup will be made in +`/var/cache/yunohost/appconfbackup/`. Otherwise, the existing file is removed. + +if `apps/$app/etc/nginx/conf.d/$domain.d/$app.conf` exists, restore it into +`/etc/nginx/conf.d/$domain.d/$app.conf` +if no, search for a match in the csv (eg: conf/nginx.conf) and restore it into +`/etc/nginx/conf.d/$domain.d/$app.conf` + +Requires YunoHost version 2.6.4 or higher. +Requires YunoHost version 3.5.0 or higher for the argument --not_mandatory + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/backup#L238) +
+ +#### ynh_store_file_checksum + +
Calculate and store a file checksum into the app settings + +**Usage**: `ynh_store_file_checksum --file=file` + +**Arguments**: +- `-f`, `--file=`: The file on which the checksum will performed, then stored. + +**Details**: +$app should be defined when calling this helper + +Requires YunoHost version 2.6.4 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/backup#L306) +
+ +#### ynh_backup_if_checksum_is_different + +
Verify the checksum and backup the file if it's different + +**Usage**: `ynh_backup_if_checksum_is_different --file=file` + +**Arguments**: +- `-f`, `--file=`: The file on which the checksum test will be perfomed. + +**Returns**: the name of a backup file, or nothing + +**Details**: +This helper is primarily meant to allow to easily backup personalised/manually +modified config files. + +Requires YunoHost version 2.6.4 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/backup#L357) +
+ +#### ynh_delete_file_checksum + +
Delete a file checksum from the app settings + +**Usage**: `ynh_delete_file_checksum --file=file` + +**Arguments**: +- `-f`, `--file=`: The file for which the checksum will be deleted + +**Details**: +$app should be defined when calling this helper + +Requires YunoHost version 3.3.1 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/backup#L397) +
+ +--- + + +### LOGGING + +#### ynh_die + +
Print a message to stderr and exit + +**Usage**: `ynh_die --message=MSG [--ret_code=RETCODE]` + +**Arguments**: +- `-m`, `--message=`: Message to display +- `-c`, `--ret_code=`: Exit code to exit with + +**Details**: +Requires YunoHost version 2.4.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/logging#L10) +
+ +#### ynh_print_info + +
Display a message in the 'INFO' logging category + +**Usage**: `ynh_print_info --message="Some message"` + +**Arguments**: +- `-m`, `--message=`: Message to display + +**Details**: +Requires YunoHost version 3.2.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/logging#L30) +
+ +#### ynh_print_warn + +
Print a warning on stderr + +**Usage**: `ynh_print_warn --message="Text to print"` + +**Arguments**: +- `-m`, `--message=`: The text to print + +**Details**: +Requires YunoHost version 3.2.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/logging#L56) +
+ +#### ynh_print_err + +
Print an error on stderr + +**Usage**: `ynh_print_err --message="Text to print"` + +**Arguments**: +- `-m`, `--message=`: The text to print + +**Details**: +Requires YunoHost version 3.2.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/logging#L73) +
+ +#### ynh_exec_err + +
Execute a command and print the result as an error + +**Usage**: `ynh_exec_err your command and args` + +**Arguments**: +- `command`: command to execute + +**Details**: +Note that you should NOT quote the command but only prefix it with ynh_exec_err + +Requires YunoHost version 3.2.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/logging#L92) +
+ +#### ynh_exec_warn + +
Execute a command and print the result as a warning + +**Usage**: `ynh_exec_warn your command and args` + +**Arguments**: +- `command`: command to execute + +**Details**: +Note that you should NOT quote the command but only prefix it with ynh_exec_warn + +Requires YunoHost version 3.2.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/logging#L113) +
+ +#### ynh_exec_warn_less + +
Execute a command and force the result to be printed on stdout + +**Usage**: `ynh_exec_warn_less your command and args` + +**Arguments**: +- `command`: command to execute + +**Details**: +Note that you should NOT quote the command but only prefix it with ynh_exec_warn + +Requires YunoHost version 3.2.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/logging#L134) +
+ +#### ynh_exec_quiet + +
Execute a command and redirect stdout in /dev/null + +**Usage**: `ynh_exec_quiet your command and args` + +**Arguments**: +- `command`: command to execute + +**Details**: +Note that you should NOT quote the command but only prefix it with ynh_exec_warn + +Requires YunoHost version 3.2.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/logging#L155) +
+ +#### ynh_exec_fully_quiet + +
Execute a command and redirect stdout and stderr in /dev/null + +**Usage**: `ynh_exec_quiet your command and args` + +**Arguments**: +- `command`: command to execute + +**Details**: +Note that you should NOT quote the command but only prefix it with ynh_exec_quiet + +Requires YunoHost version 3.2.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/logging#L176) +
+ +#### ynh_exec_and_print_stderr_only_if_error + +
Execute a command and redirect stderr in /dev/null. Print stderr on error. + +**Usage**: `ynh_exec_and_print_stderr_only_if_error your command and args` + +**Arguments**: +- `command`: command to execute + +**Details**: +Note that you should NOT quote the command but only prefix it with ynh_exec_and_print_stderr_only_if_error + +Requires YunoHost version 11.2 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/logging#L197) +
+ +#### ynh_script_progression + +
Print a progress bar showing the progression of an app script + +**Usage**: `ynh_script_progression --message=message [--weight=weight] [--time]` + +**Arguments**: +- `-m`, `--message=`: The text to print +- `-w`, `--weight=`: The weight for this progression. This value is 1 by default. Use a bigger value for a longer part of the script. +- `-t`, `--time`: Print the execution time since the last call to this helper. Especially usefull to define weights. The execution time is given for the duration since the previous call. So the weight should be applied to this previous call. +- `-l`, `--last`: Use for the last call of the helper, to fill the progression bar. + +**Details**: +Requires YunoHost version 3.5.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/logging#L257) +
+ +#### ynh_return + +
Return data to the YunoHost core for later processing +(to be used by special hooks like app config panel and core diagnosis) + +**Usage**: `ynh_return somedata` + +**Details**: +Requires YunoHost version 3.6.0 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/logging#L345) +
+ +--- + + +### MULTIMEDIA + +#### ynh_multimedia_build_main_dir + +
Initialize the multimedia directory system + +**Usage**: `ynh_multimedia_build_main_dir` + +**Details**: +Requires YunoHost version 4.2 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/multimedia#L11) +
+ +#### ynh_multimedia_addfolder + +
Add a directory in yunohost.multimedia + +**Usage**: `ynh_multimedia_addfolder --source_dir="source_dir" --dest_dir="dest_dir"` + +**Arguments**: +- `-s`, `--source_dir=`: Source directory - The real directory which contains your medias. +- `-d`, `--dest_dir=`: Destination directory - The name and the place of the symbolic link, relative to "/home/yunohost.multimedia" + +**Details**: +This "directory" will be a symbolic link to a existing directory. + +Requires YunoHost version 4.2 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/multimedia#L64) +
+ +#### ynh_multimedia_addaccess + +
Allow an user to have an write authorisation in multimedia directories + +**Usage**: `ynh_multimedia_addaccess user_name` + +**Arguments**: +- `-u`, `--user_name=`: The name of the user which gain this access. + +**Details**: +Requires YunoHost version 4.2 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/multimedia#L93) +
+ +--- + + +## Deprecated Or Handled By The Core / App Resources Since V2 + + + + + +### PERMISSION + +#### ynh_permission_has_user + +
Check if a permission has an user + +**Usage**: `ynh_permission_has_user --permission=permission --user=user +| exit: Return 1 if the permission doesn't have that user or doesn't exist, 0 otherwise` + +**Arguments**: +- `-p`, `--permission=`: the permission to check +- `-u`, `--user=`: the user seek in the permission + +**Example**: `ynh_permission_has_user --permission=main --user=visitors` + +**Details**: +Requires YunoHost version 3.7.1 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/permission#L339) +
+ +--- + + +### APT + +#### ynh_package_is_installed + +
Check either a package is installed or not + +**Usage**: `ynh_package_is_installed --package=name` + +**Arguments**: +- `-p`, `--package=`: the package name to check + +**Returns**: 0 if the package is installed, 1 else. + +**Example**: `ynh_package_is_installed --package=yunohost && echo "installed"` + +**Details**: +Requires YunoHost version 2.2.4 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/apt#L53) +
+ +--- + + +### SYSTEMUSER + +#### ynh_exec_as + +
Execute a command as another user + +**Usage**: `ynh_exec_as $USER COMMAND [ARG ...]` + +**Details**: +Requires YunoHost version 4.1.7 or higher. + + +[Dude, show me the code!](https://github.com/YunoHost/yunohost/blob/2d2693507978b04c900c6aa90210cab996f317e7/helpers/helpers.v1.d/systemuser#L133) +
+ +--- +