doc/packaging_apps_hooks_fr.md

Usage des hooks YunoHost

Les hooks permettent de déclencher un script lorsqu'une action est effectuée par le système.
Le cas le plus évident, est l'ajout d'un utilisateur. Si l'app dispose d'un hook post_user_create, ce hook sera déclenché dés qu'un utilisateur sera ajouté.
Cela permet donc à une application d'exécuter des actions en fonction des évènements intervenant sur le système.

Liste des hooks disponibles

• post_domain_add
  Après l'ajout d'un domaine.
• post_domain_remove
  Après la suppression d'un domaine.
• post_user_create
  Après l'ajout d'un utilisateur.
• post_user_delete
  Après la suppression d'un utilisateur.
• post_iptable_rules
  Après le rechargement du parefeu.
• pre_backup_delete
  Avant la suppression d'un backup.
• post_backup_delete
  Après la suppression d'un backup.
• post_app_addaccess
  Après l'ajout d'un utilisateur autorisé sur une application.
• post_app_removeaccess
  Après la suppression de l'autorisation d'un utilisateur sur une application.
• post_app_clearaccess
  Après l'effacement de toute les règles d'accès sur une application.
• post_app_install Après l'installation d'une application
• post_app_upgrade Après l'upgrade d'une applications
• post_app_remove Après la supression d'une applications
• post_app_change_url Après avoir modifié le chemin et ou le nom de domaine d'une application
• post_cert_update Après la mise à jour d'un certificat
• conf_regen
  Avant et après la régénération de la configuration d'un service.
  Services pris en charge par regen-conf:
• avahi-daemon
• dnsmasq
• dovecot
• fail2ban
• glances
• metronome
• mysql
• nginx
• nslcd
• nsswitch
• postfix
• rspamd
• slapd
• ssh
• ssl

Mise en place des hooks

A l'exception du hook conf_regen, tout les hooks s'utilisent de la même manière.
Tout d'abord, il faut comprendre qu'un hook est un simple script bash qui sera exécuté par YunoHost lorsque l'évènement indiqué se présentera.
Pour ajouter un hook à YunoHost, il faut utiliser un dossier "hooks" à la racine du package de l'application. Puis dans celui-ci mettre votre script sous le nom du hooks correspondant.

Par exemple:
Pour un hook post_user_create, le script qui devra être exécuté pour ce hook doit simplement être placé dans "hooks/post_user_create" dans le package.

Lors de l'installation et de l'upgrade, les scripts dans le dossier hooks seront dupliqués dans le dossier "/etc/yunohost/hooks.d/" dans le dossier correspondant au hook, puis sous le nom "50-$app".
Lors de la suppression de l'application, tout les hooks lui appartenant seront supprimés.

Construire un script de hook

En tant que script bash, un script de hook doit commencer par le shebang bash

#!/bin/bash

Ensuite il convient de prendre les arguments donnés par YunoHost lors de l'appel du script.
Chaque hook propose des arguments différents.

post_domain_add et post_domain_remove

domain=$1

post_user_create

username=$1
mail=$2
password=$3 # Clear password
firstname=$4
lastname=$5

post_user_delete

username=$1
purge=$2  # True/False Indique si le dossier utilisateur a été supprimé ou pas.

post_iptable_rules

upnp=$1  # True/False Indique si l'upnp est activé ou non.
ipv6=$2  # True/False Indique si l'IPV6 est activé ou non.

pre_backup_delete et post_backup_delete

backup_name=$1

post_app_install, post_app_upgrade, post_app_remove et post_app_change_url

Les variables utilisables dans ces scripts sont les mêmes que celles disponibles dans les scripts d'actions associés.

Example: pour post_app_install les variables sont les mêmes que pour le script install

post_app_addaccess et post_app_removeaccess

app_id=$1
users=$2  # Tous les utilisateurs autorisés sur l'app. Séparés par des virgules.

post_app_clearaccess

app_id=$1

post_cert_update

domain=$1

La suite du script dépend de ce que vous voulez effectuer dans celui-ci.

Cas particulier de conf_regen

Le hook conf_regen est un hook plus délicat, que ce soit pour sa mise en place ou pour son contenu.

Mise en place d'un hook conf_regen

Un hook conf_regen ne doit pas être placé dans le dossier hooks de l'application. Il doit être mis en place manuellement.
Le hook doit être copié en indiquant à quel service il est lié.

cp hook_regen_conf /usr/share/yunohost/hooks/conf_regen/50-SERVICE_$app

Lors de la suppression de l'application, ce hook devra être supprimé manuellement.

Construire un script de hook conf_regen

Un hook conf_regen est appelé 2 fois, une première fois après analyse de la configuration et avant une éventuelle modification des fichiers, puis une seconde fois après application des modifications, si il y a eu des modifications.

Un script de hook conf_regen devrait donc ressembler à ça:

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

do_pre_regen() {
  # Put your code here for pre regen conf.
}

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

case "$1" in
  pre)
    do_pre_regen
    ;;
  post)
    do_post_regen
    ;;
  *)
    echo "Hook called with unknown argument \`$1'" >&2
    exit 1
    ;;
esac

exit 0