diff --git a/pages/06.contribute/10.packaging_apps/11.helpers/packaging_apps_helpers.md b/pages/06.contribute/10.packaging_apps/11.helpers/packaging_apps_helpers.md index 3ac76d15..610a14ec 100644 --- a/pages/06.contribute/10.packaging_apps/11.helpers/packaging_apps_helpers.md +++ b/pages/06.contribute/10.packaging_apps/11.helpers/packaging_apps_helpers.md @@ -7,8 +7,11 @@ routes: default: '/packaging_apps_helpers' --- + + Doc auto-generated by [this script](https://github.com/YunoHost/yunohost/blob/6fc6a2ba4c17434803cea2553a3dc7c51cedd338/doc/generate_helper_doc.py) on 03/29/2022 (YunoHost version 4.3.6.3) +!!! Tips: if you are not in an app script, you can use a lot of this helpers by running before `source /usr/share/yunohost/helpers ; app=custom` ## APT diff --git a/pages/06.contribute/10.packaging_apps/12.hooks/packaging_apps_hooks.fr.md b/pages/06.contribute/10.packaging_apps/12.hooks/packaging_apps_hooks.fr.md index 892091b6..c4650902 100644 --- a/pages/06.contribute/10.packaging_apps/12.hooks/packaging_apps_hooks.fr.md +++ b/pages/06.contribute/10.packaging_apps/12.hooks/packaging_apps_hooks.fr.md @@ -6,194 +6,31 @@ taxonomy: routes: default: '/packaging_apps_hooks' --- +YunoHost comprend un mécanisme de hooks déclenchés lors de nombreuses opérations modifiant le système. Vous pouvez utiliser ce mécanisme afin d'étendre le comportement d'une commande 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. +Le cas le plus évident est l'ajout d'un utilisateur. Si vous aviez un hook `post_user_create`, ce hook sera déclenché dès qu'un utilisateur sera ajouté. -### Liste des hooks disponibles +## Comment ajouter un hook personnalisé sur une instance spécifique +! !! Nous imaginons ci-dessous que nous voulons lancer une commande après chaque création d'utilisateur pour ajouter l'utilisateur à l'utilisateur samba. -- `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 application. -- `post_app_remove` -Après la supression d'une application. -- `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 - -À 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 hook 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, tous 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 +Vous devez créer un répertoire avec le nom des hooks dans `/etc/yunohost/hooks.d/` : +``` +mkdir -p /etc/yunohost/hooks.d/post_user_create ``` -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` - +Créez ensuite un script bash à l'intérieur de ce répertoire, préfixé par 2 chiffres et un tiret : ```bash -domain=$1 +nano /etc/yunohost/hooks.d/post_user_create/05-add-user-to-samba ``` -##### `post_user_create` - -```bash -username=$1 -mail=$2 -password=$3 # Clear password -firstname=$4 -lastname=$5 +## Comment ajouter un hook dans un paquetage d'application +Si vous empaquetez une application, vous ne devez pas mettre vous-même le hook dans `/etc/yunohost/hooks.d mais vous devez créer un répertoire hooks à la racine de votre paquet. ``` -##### `post_user_delete` - -```bash -username=$1 -purge=$2 # True/False Indique si le dossier utilisateur a été supprimé ou pas. +. +├─── conf +├─── hooks +├── scripts ``` +Dans le dossier des hooks, créer un script bash appelé avec le type de hook que vous voulez créer par exemple `post_create_user`. -##### `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_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](/packaging_apps_scripts). - - -Exemple : pour `post_app_install` les variables sont les mêmes que pour le script `install` - -##### `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 -``` - -##### `post_cert_update` -```bash -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é. -```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, s' 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 -``` +## [Liste des hooks et leurs variables](/packaging_apps_hooks_fr) 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 52ea5c86..fad24b0d 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 @@ -9,7 +9,9 @@ routes: 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. -## How to add a hooks +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 !!! Bellow 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/`: @@ -22,6 +24,17 @@ 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 ``` +## 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