diff --git a/pages/02.administer/60.extend/05.install_unpackaged_app/install_unpackaged_app.md b/pages/02.administer/60.extend/05.install_unpackaged_app/install_unpackaged_app.md index 6d611b89..d2911d1d 100644 --- a/pages/02.administer/60.extend/05.install_unpackaged_app/install_unpackaged_app.md +++ b/pages/02.administer/60.extend/05.install_unpackaged_app/install_unpackaged_app.md @@ -7,4 +7,23 @@ routes: default: '/install_unpackaged_apps' --- -!! This page is to be written + +## PHP or HTML/JS apps +If your app is a PHP or HTML/JS app, you probably should use the `Custom Webapp`, also know as `my_webapp`, in order to configure nginx, php, mysql, yunohost permission and backup for you. + +## Other technologies + +If you use an other techno, you should install it like on a classical debian. + +To expose the app on the web through nginx and be able to manage access permissions to the webapp, you could use the `redirect` app to create a nginx reverse proxy on your local ip/port running the service. + +!!! You should use the proxy mode of the redirect app and not HTTP redirections mode. + +If you know a bit YunoHost, you can use the [yunohost helpers](/helpers) to do your install to be close to the way YunoHost install its packaged apps. To use those helpers, you have to initialize first your CLI by this way: + +``` +source /usr/share/yunohost/helpers +app=YOURAPPNAME +``` + +You probably should create custom backup and restore hooks to integrate your app to your YunoHost backup/restore process. See [Backup and restore hooks]() diff --git a/pages/02.administer/60.extend/15.theming/theming.md b/pages/02.administer/60.extend/15.theming/theming.md index 7968e6ec..f4ae2baf 100644 --- a/pages/02.administer/60.extend/15.theming/theming.md +++ b/pages/02.administer/60.extend/15.theming/theming.md @@ -7,6 +7,14 @@ routes: default: '/theming' --- +## Globally disable the overlay + +You can disable the overlay by changing the dedicated settings: + +``` +yunohost settings set ssowat.panel_overlay.enabled -v 0 +``` + ## Using a theme Since YunoHost 3.5, you can change the theme of the user portal - though for now it requires tweaking via the command line. diff --git a/pages/06.contribute/10.packaging_apps/12.hooks/packaging_apps_hooks.md b/pages/06.contribute/10.packaging_apps/12.hooks/packaging_apps_hooks.md index 16056b85..52ea5c86 100644 --- a/pages/06.contribute/10.packaging_apps/12.hooks/packaging_apps_hooks.md +++ b/pages/06.contribute/10.packaging_apps/12.hooks/packaging_apps_hooks.md @@ -7,192 +7,703 @@ routes: default: '/packaging_apps_hooks' --- -Hooks allow you to trigger a script when an action is performed by the system. -The most obvious case is adding a user. If the app has a `post_user_create` hook, this hook will be triggered as soon as a user is added. -Therefore, this allows an application to execute actions based on events occurring on the system. +YunoHost includes a hook mechanism triggered on a lot of operation changing the system. You can use this mechanism in order to extend the behaviour of a yunohost command. -### List of available hooks +## How to add a hooks +!!! Bellow we imagine we want to run a command after each user creation to add the user to samba user. -- `post_domain_add` -After adding a domain. -- `post_domain_remove` -After deleting a domain. -- `post_user_create` -After adding a user. -- `post_user_delete` -After deleting a user. -- `post_iptable_rules` -After reloading the firewall. -- `pre_backup_delete` -Before deleting a backup. -- `post_backup_delete` -After deleting a backup. -- `post_app_addaccess` -After adding an authorized user to an application. -- `post_app_removeaccess` -After the removal of a user's authorization on an application. -- `post_app_clearaccess` -After erasing all the access rules on an application. -- `post_app_install` -After installing an application. -- `post_app_upgrade` -After upgrading an application. -- `post_app_remove` -After removing an application. -- `post_app_change_url` -After modifying the path and/or the domain name of an application. -- `post_cert_update` -After updating a certificate -- `conf_regen` -Before and after the regeneration of a service configuration. -Services supported by `regen-conf`: - - avahi-daemon - - dnsmasq - - dovecot - - fail2ban - - glances - - metronome - - mysql - - nginx - - nslcd - - nsswitch - - postfix - - rspamd - - slapd - - ssh - - ssl +You should create a directory with the name of the hooks into `/etc/yunohost/hooks.d/`: +``` +mkdir -p /etc/yunohost/hooks.d/post_user_create +``` -### Hooks setup +Next create a bash script inside this directory prefixed by 2 numbers and a dash: +```bash +nano /etc/yunohost/hooks.d/post_user_create/05-add-user-to-samba +``` -With the exception of the `conf_regen` hook, all hooks are used in the same way. -First of all, you have to understand that a hook is a simple bash script that will be executed by YunoHost when the indicated event occurs. -To add a hook to YunoHost, you must use a "hooks" folder at the root of the application package. Then, put your script in this folder under the name of the corresponding hook. +## Hooks referencies +### User and permissions +#### post_user_create +[details summary="Triggered after user creation" class="helper-card-subtitle text-muted"] -> For example: -For the hook `post_user_create`, the script which will have to be executed for this hook should be placed in `hooks/post_user_create` in the app package. +This hooks is run at the end of the command `yunohost user create` or equivalent action in webadmin. -During the installation and the upgrade of the application, the scripts in the hooks folder will be duplicated in the folder `/etc/yunohost/hooks.d/` in the folder corresponding to the hook, then under the name `50-$app`. -All hooks belonging to an application will be removed when the apllication is deleted. +##### Environment variables -### Building a hook script + - YNH_USER_USERNAME: The username of the created user + - YNH_USER_MAIL: The mail of the created user + - YNH_USER_PASSWORD: The **clear** password of the created user + - YNH_USER_FIRSTNAME: The firstname of the created user ([should be removed in future](https://github.com/YunoHost/issues/issues/296)) + - YNH_USER_LASTNAME: The lastname of the created user ([should be removed in future](https://github.com/YunoHost/issues/issues/296)) -As a bash script, a hook script must start with the bash shebang. +##### Positionnal arguments (deprecated) + - $1: The username of the created user + - $2: The mail of the created user + +##### No waited return + +##### Examples + +###### Send automatically a mail to new user +```bash +#!/bin/bash +domain=$(cat /etc/hostname) + +message="Hello $YNH_USER_FIRSTNAME, +Welcome on $domain ! +Feel free to change your password. +Let me know if you have a problem, +The admin of $domain +" + +echo $message | mail -s "Welcome on $domain !" $YNH_USER_MAIL +``` + +###### Add the user to samba + +##### Hook changelog + - + +[/details] + + + +#### post_user_delete +[details summary="Triggered at the end of user deletion" class="helper-card-subtitle text-muted"] + +This hooks is run at the end of the command `yunohost user delete` or equivalent action in webadmin. + +##### No environment variables + +##### Positionnal arguments + + - $1: The username of the user deleted + - $2: True if --purge option is used + +##### No waited return + +##### Examples + +###### ```bash #!/bin/bash ``` -Then you have to take the arguments given by YunoHost when calling the script. -Each hook offers different arguments. +##### Hook changelog + - -##### `post_domain_add` and `post_domain_remove` +[/details] + + +### post_user_update +[details summary="Triggered at the end of the user update" class="helper-card-subtitle text-muted"] + +This hooks is run at the end of the command `yunohost user update` or equivalent action in webadmin. + +##### Environment variables + +! Only arguments given to the cli/api are given as environment variable. + - YNH_USER_USERNAME: The username of the updated user + - YNH_USER_FIRSTNAME: The firstname of the updated user ([should be removed in future](https://github.com/YunoHost/issues/issues/296)) + - YNH_USER_LASTNAME: The lastname of the updated user ([should be removed in future](https://github.com/YunoHost/issues/issues/296)) + - YNH_USER_PASSWORD: The new password of the updated user + - YNH_USER_MAILS: The mail and mail aliases of the updated user seperated by comma + - YNH_USER_MAILFORWARDS: The list of forward mails of the updated user separated by comma + - YNH_USER_MAILQUOTA: The quota of the updated user (could be 0 or a number following by one of this unit: b, k, M, G or T) + +##### No positionnal arguments + +##### No waited return + +##### Examples + +###### Send a mail on password changing ```bash -domain=$1 +#!/bin/bash +" +domain=$(cat /etc/hostname) + +message="Hello, +Your password has been successfully changed on $domain. +If you have not asked for changing your password, you probably should contact the admin of $domain. +" + +echo $message | mail -s "Your password has been changed on $domain !" $YNH_USER_USERNAME ``` -##### `post_user_create` -```bash -username=$1 -mail=$2 -password=$3 # Clear password -firstname=$4 -lastname=$5 -``` -##### `post_user_delete` +##### Hook changelog + - +[/details] + + + +### post_app_addaccess +[details summary="Triggered after adding a permission to users or groups " class="helper-card-subtitle text-muted"] + +This hooks is run at the end of the command `yunohost user permission add` or equivalent action in webadmin. + +##### No environment variables + +##### Positionnal arguments (deprecated) + + - $1: The app name + - $2: The list of users added separated by comma + - $3: The name of the sub permission (`main`, `admin`, etc.) + - $4: The list of groups added separated by comma + +##### No waited return + +##### Examples + +##### Hook changelog + - + +[/details] + + + +### post_app_removeaccess +[details summary="Triggered after removing a pemission to users or groups" class="helper-card-subtitle text-muted"] + +This hooks is run at the end of the command `yunohost user permission remove` or equivalent action in webadmin. + +##### No environment variables + +##### Positionnal arguments (deprecated) + + - $1: The app name + - $2: The list of users removed from the permission separated by comma + - $3: The name of the sub permission (`main`, `admin`, etc.) + - $4: The list of groups removed from the permission separated by comma + +##### No waited return + +##### Examples + + +##### Hook changelog + - + +[/details] + + + + + + + +## Domain, certificates and DNS +### post_domain_add +[details summary="Triggered at the end of the domain add operation" class="helper-card-subtitle text-muted"] + +This hooks is run at the end of the command `yunohost domain add` or equivalent action in webadmin. + +##### No environment variable + +##### Positionnal arguments (deprecated) + + - $1: The domain added + +##### No waited return + +##### Examples + +###### ```bash -username=$1 -purge=$2 # True/False Indicates whether the user folder has been deleted or not. + ``` -##### `post_iptable_rules` +##### Hook changelog + - +[/details] + + + + +### post_domain_remove +[details summary="Triggered after removing the domain" class="helper-card-subtitle text-muted"] + +This hooks is run at the end of the command `yunohost domain remove` or equivalent action in webadmin. + +##### No environment variable + +##### Positionnal arguments (deprecated) + + - $1: The domain removed + +##### No waited return + +##### Examples + +###### ```bash -upnp=$1 # True/False Indicates if UPnP is activated or not. -ipv6=$2 # True/False Indicates whether IPV6 is enabled or not. ``` -##### `pre_backup_delete` and `post_backup_delete` +##### Hook changelog + - +[/details] + + + + +### post_cert_update +[details summary="Triggered after Let's encrypt certificate update" class="helper-card-subtitle text-muted"] + +This hooks is run at the end of the command `yunohost domain cert update` or equivalent action in webadmin. + +##### No environment variable + +##### Positionnal arguments + + - $1: The domain for which we have updated the certificate + +##### No waited return + +##### Examples + +###### Restart a service after cert renewal ```bash -backup_name=$1 +systemctl restart gemserv ``` -##### `post_app_install`, `post_app_upgrade`, `post_app_remove` and `post_app_change_url` +##### Hook changelog + - -Usable variables in these scripts are the same as those available in [associated actions scripts](/packaging_apps_scripts). +[/details] -Example: for `post_app_install` the variables are the same as for the script `install` -##### `post_app_addaccess` and `post_app_removeaccess` -```bash -app_id=$1 -users=$2 # All authorized users on the app. Separated by commas. + +### custom_dns_rules +[details summary="Customized your DNS rules for your domains" class="helper-card-subtitle text-muted"] + +This hooks is run at the end of the command `yunohost domain dns suggest` or equivalent action in webadmin. + +Thanks to this hooks you can customize + +##### No environment variable + +##### Positionnal arguments + + - $1: The base domain for which we want to build a DNS suggestion + +##### Waited return +The script should return a JSON array with dictionnary in this format: +```json +[ + { + 'type': 'SRV', + 'name': 'stuff.foo.bar', + 'value': 'yoloswag', + 'ttl': 3600 + } +] ``` -##### `post_app_clearaccess` +##### Examples + +###### Validate Let's Encrypt DNS challenge with a YunoHost DynDNS domain ```bash -app_id=$1 +#!/bin/bash +if [[ "$1" == "XXXX.nohost.me" ]] ; then + echo "[ + { + 'type': 'TXT', + 'name': '_acme-challenge', + 'value': 'LETSENCRYPT_VALUE', + 'ttl': 3600 + } + ]" +fi + ``` -##### `post_cert_update` +##### Hook changelog + - + +[/details] + + + + + +## Apps +### post_app_change_url +[details summary="Triggered after an app has changed of URL" class="helper-card-subtitle text-muted"] + +This hooks is run at the end of the command `yunohost app change-url` or equivalent action in webadmin. + +##### Environment variables + + - YNH_APP_OLD_DOMAIN: The old domain of the app + - YNH_APP_OLD_PATH: The old path of the app + - YNH_APP_NEW_DOMAIN: The new domain of the app + - YNH_APP_NEW_PATH: The new path of the app + +##### No positionnal arguments + +##### No waited return + +##### Examples + +###### ```bash -domain=$1 ``` -The rest of the script depends on what you want to do in it. +##### Hook changelog + - -### `conf_regen` special case -The `conf_regen` hook is a more delicate hook, either for its implementation or for its content. +[/details] +### post_app_upgrade +[details summary="Triggered on app upgrade" class="helper-card-subtitle text-muted"] -##### `conf_regen` hook setup +This hooks is run at the end of the command `yunohost app upgrade` or equivalent action in webadmin. -A `conf_regen` hook should not be placed in the application's hooks folder. It must be set up manually. -The hook should be copied, indicating to which service it is linked. -```bash -cp hook_regen_conf /usr/share/yunohost/hooks/conf_regen/50-SERVICE_$app -``` +##### Environment variables -> When removing the application, this hook must be removed manually. + - YNH_APP_ID: The app id (for example nextcloud) + - YNH_APP_INSTANCE_NAME: The app instance name (for example nextcloud__2) + - YNH_APP_INSTANCE_NUMBER: The app instance number (for example 2) + - YNH_APP_MANIFEST_VERSION: The app manifest version (for example 1 or ?) + - YNH_ARCH: The arch as returned by `dpkg --print-architecture` + - YNH_APP_UPGRADE_TYPE: The type of upgrade (UPGRADE_PACKAGE, UPGRADE_APP, UPGRADE_FULL) + - YNH_APP_MANIFEST_VERSION: The version number + - YNH_APP_CURRENT_VERSION: The version number of the app (in the yunohost format) + - NO_BACKUP_UPGRADE: 1 if we don't want to backup else 0 -##### Building `conf_regen` hook script +##### No positionnal arguments -`conf_regen` hook is called two times, a first time after analysis of the configuration and before any modification of the files, then a second time after applying the modifications, if there has been modifications. +##### No waited return -`conf_regen` hook script should look like this: +##### Examples +###### Change a settings in an app config file (unmanaged by config panel) ```bash #!/bin/bash -force=${2:-0} # 0/1 --force argument -dryrun=${3:-0} # 0/1 --dry-run argument -pending_conf=$4 # Path of the pending conf file +source /usr/share/yunohost/helpers +app=$YNH_APP_INSTANCE_NAME -do_pre_regen() { - # Put your code here for pre regen conf. +if [[ "$app" == "etherpad_mypads" ]]; then + ynh_write_var_in_file --file=/var/www/etherpad_mypads/settings.json --key=max --value=100 --after=importExportRateLimiting + systemctl restart etherpad_mypads +fi + +``` + +##### Hook changelog + - + + +[/details] +### post_app_install +[details summary="Triggered at the end of an app installation" class="helper-card-subtitle text-muted"] + +This hooks is run at the end of the command `yunohost app install` or equivalent action in webadmin. + +##### Environment variables + + - YNH_APP_ID: The app id (for example nextcloud) + - YNH_APP_INSTANCE_NAME: The app instance name (for example nextcloud__2) + - YNH_APP_INSTANCE_NUMBER: The app instance number (for example 2) + - YNH_APP_MANIFEST_VERSION: The app manifest version (for example 1 or ?) + - YNH_ARCH: The arch as returned by `dpkg --print-architecture` + - YNH_APP_ARG_XXXXXXX: The argument of the manifest + +##### No positionnal arguments + +##### No waited return + +##### Examples + +###### +```bash +#!/bin/bash + +``` + +##### Hook changelog + - + + +[/details] +### post_app_remove +[details summary="Triggered after removing an app" class="helper-card-subtitle text-muted"] + +This hooks is run at the end of the command `yunohost app remove` or equivalent action in webadmin. + +##### Environment variables + + - YNH_APP_ID: The app id (for example nextcloud) + - YNH_APP_INSTANCE_NAME: The app instance name (for example nextcloud__2) + - YNH_APP_INSTANCE_NUMBER: The app instance number (for example 2) + - YNH_APP_MANIFEST_VERSION: The app manifest version (for example 1 or ?) + - YNH_ARCH: The arch as returned by `dpkg --print-architecture` + - YNH_APP_PURGE: 1 if the --purge option has been activated + +##### No positionnal arguments + +##### No waited return + +##### Examples + +###### +```bash +#!/bin/bash + +``` + +##### Hook changelog + - + + +[/details] + +## Backup / Restore +### backup +[details summary="Add some files to backup" class="helper-card-subtitle text-muted"] + +This hooks is run at the end of the command `yunohost backup create` or equivalent action in webadmin. + +##### Environment variables + + - YNH_BACKUP_DIR: The work dir in which we can store temporary data to backup like database dump + - YNH_BACKUP_CSV: The CSV in which we add the things to backup. Don't use this directly and use ynh_backup helper instead. + - YNH_APP_BACKUP_DIR: To document + +##### Positionnal arguments + - $1: The work dir in which we can store temporary data to backup like database dump + +##### No waited return + +##### Examples + +###### Backup some files in more (for example your custom hooks) +```bash +#!/bin/bash + +# Source YNH helpers +source /usr/share/yunohost/helpers + +ynh_backup_dest (){ + YNH_CWD="${YNH_BACKUP_DIR%/}/$1" + mkdir -p $YNH_CWD + cd "$YNH_CWD" } -do_post_regen() { - # Put your code here for post regen conf. - # Be careful, this part will be executed only if the configuration has been modified. +# Exit hook on subcommand error or unset variable +ynh_abort_if_errors + +# MISC +ynh_backup_dest "conf/custom/misc" +ynh_backup "/etc/sysctl.d/noipv6.conf" +ynh_backup "/usr/local/bin/" + +ynh_backup "/etc/yunohost/hooks.d/backup/99-conf_custom" +ynh_backup "/etc/yunohost/hooks.d/restore/99-conf_custom" + +``` + +##### Hook changelog + - + + +[/details] + +### restore +[details summary="Restore some files" class="helper-card-subtitle text-muted"] + +This hooks is run at the end of the command `yunohost backup restore` or equivalent action in webadmin. + +##### Environment variables + + - YNH_BACKUP_DIR: The work dir in which we can store temporary data to backup like database dump + - YNH_BACKUP_CSV: The CSV in which we add the things to backup. Don't use this directly and use ynh_backup helper instead. + +##### Positionnal arguments + - $1: The work dir in which we can store temporary data to backup like database dump + +##### No waited return + +##### Examples + +###### +```bash +#!/bin/bash + +# Source YNH helpers +source /usr/share/yunohost/helpers + +ynh_restore_dest (){ + YNH_CWD="${YNH_BACKUP_DIR%/}/$1" + cd "$YNH_CWD" } +# Exit hook on subcommand error or unset variable +ynh_abort_if_errors + +# MISC +ynh_restore_dest "conf/custom/misc" +ynh_restore_file "/etc/sysctl.d/noipv6.conf" +ynh_restore_file "/usr/local/bin/" + +ynh_restore_file "/etc/yunohost/hooks.d/backup/99-conf_custom" +ynh_restore_file "/etc/yunohost/hooks.d/restore/99-conf_custom" + + +``` + +##### Hook changelog + - + + +[/details] +### backup_method +[details summary="Define a new way to backup and restore files" class="helper-card-subtitle text-muted"] + +This hooks is run during the command `yunohost backup create` or equivalent action in webadmin. + +This hook is called several times with different action keywords. + +##### No environment variables + +##### Positionnal arguments + + + - $1: The action ("need_mount", "backup", "mount") + - $2: The work dir + - $3: The name of the backup + - $4: The repository in which the backup should be done + - $5: An estimation size of the files to backup + - $6: A description of the archive + + +##### No waited return + +##### Examples + +###### A very simple backup on rotationnal disks +```bash +#!/bin/bash +set -euo pipefail + +work_dir="$2" +name="$3" +repo="$4" +size="$5" +description="$6" + case "$1" in - pre) - do_pre_regen + need_mount) + # Set false if your method can itself put files in good place in your archive + true ;; - post) - do_post_regen + backup) + mount /dev/sda1 /mnt/hdd + if [[ "$(df /mnt/hdd | tail -n1 | cut -d" " -f1)" != "/dev/sda1" ]] + then + exit 1 + fi + pushd "$work_dir" + current_date=$(date +"%Y-%m-%d_%H:%M") + cp -a "${work_dir}" "/mnt/hdd/${current_date}_$name" + popd + umount /mnt/hdd ;; *) - echo "Hook called with unknown argument \`$1'" >&2 + echo "hook called with unknown argument \`$1'" >&2 exit 1 ;; esac exit 0 + ``` + +##### Hook changelog + - + + +[/details] + +## Configuration and firewall +### post_iptable_rules +[details summary="Triggered after reloaded the firewall rules" class="helper-card-subtitle text-muted"] + +This hooks is run at the end of the command `yunohost firewall reload` or equivalent action in webadmin. + +##### No environment variables + + +##### Positionnal arguments + + - $1: True if upnp has succeeded + - $2: True if ipv6 is available + +##### No waited return + +##### Examples + +###### Forbid completely the outgoing 25 port +```bash +#!/bin/bash +iptables -A OUTPUT -p tcp -m tcp --dport 25 -j ACCEPT +``` + +##### Hook changelog + - + + +[/details] + +### conf_regen +[details summary="Change configuration suggested as default config in regen-conf mechanism" class="helper-card-subtitle text-muted"] + +This hooks is run during the command `yunohost tools regen-conf` or equivalent action in webadmin. + +This hook is called several times with different actions keywords (pre and post operations). + +##### Environment variables + + - YNH_DOMAINS: The list of domains managed by Yunohost separated by comma + - YNH_MAIN_DOMAINS: The list of main domains separated by comma + +##### Positionnal arguments + + - $1: The pre or post action + - $2: Empty string due to legacy + - $3: Empty string due to legacy + - $4: In post mode the list of file which should be modified. In pre mode the dir in which we store pending configuration + +##### No waited return + +##### Examples + +###### Fix the warning about postfix compatibility mode in postfix logs +```bash +#!/bin/bash + +action=$1 +pending_dir=$4 +postfix_conf=$pending_dir/../postfix/etc/postfix/main.cf + +[[ "$action" == "pre" ]] || exit 0 +[[ -e $postfix_conf ]] || exit 0 +echo ' +compatibility_level = 2' >> $postfix_conf +``` + +##### Hook changelog + - + + +[/details] +