doc/pages/06.contribute/10.packaging_apps/60.advanced/50.hooks/packaging_apps_hooks.md

title	template	taxonomy	routes
Hooks	docs	category docs	default /packaging_apps_hooks

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.

The most obvious case is adding a user. If you had a post_user_create hook, this hook will be triggered as soon as a user is added.

How to add a custom hook on a specific instance

!!! Below we imagine we want to run a command after each user creation to add the user to samba user.

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

Next create a bash script inside this directory prefixed by 2 numbers and a dash:

nano /etc/yunohost/hooks.d/post_user_create/05-add-user-to-samba

By default, the directory must be readable and traversable by root, but if you notice your hook is not run at all by YunoHost, you can check permissions with ls -l /etc/yunohost/hooks.d/ and apply these commands if needed:

chown root:root /etc/yunohost/hooks.d/post_user_create
chmod u+rx /etc/yunohost/hooks.d/post_user_create

How to add a hook in an app package

If you are packaging an app, you should not set by yourself the hook into /etc/yunohost/hooks.d instead you should create a hooks dir at the root of your package.

.
├── conf
├── hooks
├── scripts

In the hooks dir, create a bash script called with the type of hook you want to create for example post_create_user.

Hooks referencies

User and permissions

post_user_create

[details summary="Triggered after user creation" class="helper-card-subtitle text-muted"]

This hook is run at the end of the command yunohost user create or equivalent action in webadmin.

Environment variables

• 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)
• YNH_USER_LASTNAME: The lastname of the created user (should be removed in future)

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

#!/bin/bash
domain=$(cat /etc/hostname)

message="Hello $YNH_USER_FIRSTNAME,
Welcome on $domain ! 
Feel free to <a href='https://$domain/yunohost/sso/edit.html'>change your password</a>.
Let me know if you have a problem,
The admin of $domain
"

echo $message | mail -s "Welcome on $domain !" $YNH_USER_MAIL

[/details]

post_user_delete

[details summary="Triggered at the end of user deletion" class="helper-card-subtitle text-muted"]

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

#!/bin/bash

[/details]

post_user_update

[details summary="Triggered at the end of the user update" class="helper-card-subtitle text-muted"]

This hook 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)
• YNH_USER_LASTNAME: The lastname of the updated user (should be removed in future)
• 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

#!/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

[/details]

post_app_addaccess

[details summary="Triggered after adding a permission to users or groups " class="helper-card-subtitle text-muted"]

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

[/details]

post_app_removeaccess

[details summary="Triggered after removing a pemission to users or groups" class="helper-card-subtitle text-muted"]

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

[/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 hook 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

[/details]

post_domain_remove

[details summary="Triggered after removing the domain" class="helper-card-subtitle text-muted"]

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

[/details]

post_cert_update

[details summary="Triggered after Let's encrypt certificate update" class="helper-card-subtitle text-muted"]

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

#!/bin/bash
systemctl restart gemserv

[/details]

custom_dns_rules

[details summary="Customized your DNS rules for your domains" class="helper-card-subtitle text-muted"]

This hook is run at the end of the command yunohost domain dns suggest or equivalent action in webadmin.

Thanks to This hook 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:

[
    {
        'type': 'SRV',
        'name': 'stuff.foo.bar',
        'value': 'yoloswag',
        'ttl': 3600
    }
]

Examples

Validate Let's Encrypt DNS challenge with a YunoHost DynDNS domain

#!/bin/bash
if [[ "$1" == "XXXX.nohost.me" ]] ; then
    echo "[
        {
            'type': 'TXT',
            'name': '_acme-challenge',
            'value': 'LETSENCRYPT_VALUE',
            'ttl': 3600
        }
    ]"
fi

[/details]

Apps

post_app_change_url

[details summary="Triggered after an app has changed of URL" class="helper-card-subtitle text-muted"]

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

[/details]

post_app_upgrade

[details summary="Triggered on app upgrade" class="helper-card-subtitle text-muted"]

This hook is run at the end of the command yunohost app upgrade 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_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

No positionnal arguments

No waited return

Examples

Change a settings in an app config file (unmanaged by config panel)

#!/bin/bash

source /usr/share/yunohost/helpers
app=$YNH_APP_INSTANCE_NAME

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

[/details]

post_app_install

[details summary="Triggered at the end of an app installation" class="helper-card-subtitle text-muted"]

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

[/details]

post_app_remove

[details summary="Triggered after removing an app" class="helper-card-subtitle text-muted"]

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

[/details]

Backup / Restore

backup

[details summary="Add some files to backup" class="helper-card-subtitle text-muted"]

This hook 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)

#!/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"
}

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

[/details]

restore

[details summary="Restore some files" class="helper-card-subtitle text-muted"]

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

restore custom files

#!/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"

[/details]

backup_method

[details summary="Define a new way to backup and restore files" class="helper-card-subtitle text-muted"]

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

#!/bin/bash
set -euo pipefail

work_dir="$2"
name="$3"
repo="$4"
size="$5"
description="$6"

case "$1" in
  need_mount)
    # Set false if your method can itself put files in good place in your archive
    true
    ;;
  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
    exit 1
    ;;
esac

exit 0

[/details]

Configuration and firewall

post_iptable_rules

[details summary="Triggered after reloaded the firewall rules" class="helper-card-subtitle text-muted"]

This hook 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 except for postfix user

#!/bin/bash
iptables -A OUTPUT -p tcp --dport 25 -m owner --uid-owner postfix -j ACCEPT
iptables -A OUTPUT -p tcp --dport 25 -m tcp -j REJECT --reject-with icmp-port-unreachable

[/details]

conf_regen

[details summary="Change configuration suggested as default config in regen-conf mechanism" class="helper-card-subtitle text-muted"]

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

#!/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

[/details]