diff --git a/packaging_apps_fr.md b/packaging_apps_fr.md index 872bd0d0..60304894 100644 --- a/packaging_apps_fr.md +++ b/packaging_apps_fr.md @@ -39,6 +39,9 @@ Comme les instances de YunoHost possèdent une architecture unifiée, vous serez ### Multi-instance Multi-instance +### Hooks +Hooks + ### Commandes pratiques Commandes pratiques diff --git a/packaging_apps_hooks_fr.md b/packaging_apps_hooks_fr.md new file mode 100644 index 00000000..2ca12a7b --- /dev/null +++ b/packaging_apps_hooks_fr.md @@ -0,0 +1,172 @@ +# 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. +- `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 + - rmilter + - 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 + +```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` + +```bash +domain=$1 +``` + +##### `post_user_create` + +```bash +username=$1 +mail=$2 +password=$3 # Clear password +firstname=$4 +lastname=$5 +``` + +##### `post_user_delete` + +```bash +username=$1 +purge=$2 # True/False Indique si le dossier utilisateur a été supprimé ou pas. +``` + +##### `post_iptable_rules` + +```bash +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` + +```bash +backup_name=$1 +``` + +##### `post_app_addaccess` et `post_app_removeaccess` + +```bash +app_id=$1 +users=$2 # Tous les utilisateurs autorisés sur l'app. Séparés par des virgules. +``` + +##### `post_app_clearaccess` + +```bash +app_id=$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é. +```bash +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: + +```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 + +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 +``` diff --git a/sitemap_fr.md b/sitemap_fr.md index 0b13fb85..165ca0c1 100644 --- a/sitemap_fr.md +++ b/sitemap_fr.md @@ -105,6 +105,7 @@ * [Gestion des arguments](packaging_apps_arguments_management_fr) * [Configuration Nginx](packaging_apps_nginx_conf_fr) * [Multi-instance](packaging_apps_multiinstance_fr) + * [Hooks](packaging_apps_hooks_fr) * [Commandes pratiques](packaging_apps_helpers_fr) * [Usage de trap](packaging_apps_trap_fr) * [Niveaux des applications](packaging_apps_levels_fr)