Merge pull request #1329 from ericgaspar/apps_hooks

Apps hooks translation into english

packaging_apps_hooks.md

@@ -1 +1,191 @@
-Unfortunately, this page only exists [in french here](packaging_apps_hooks_fr) for now.
+# The use of YunoHost 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.
+
+### List of available hooks
+
+- `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
+
+### Hooks setup
+
+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.
+
+> 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.
+
+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.
+
+### Building a hook script
+
+As a bash script, a hook script must start with the bash shebang.
+
+```bash
+#!/bin/bash
+```
+
+Then you have to take the arguments given by YunoHost when calling the script.  
+Each hook offers different arguments.
+
+##### `post_domain_add` and `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 Indicates whether the user folder has been deleted or not.
+```
+
+##### `post_iptable_rules`
+
+```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`
+
+```bash
+backup_name=$1
+```
+
+##### `post_app_install`, `post_app_upgrade`, `post_app_remove` and `post_app_change_url`
+
+Usable variables in these scripts are the same as those available in [associated actions scripts](/packaging_apps_scripts).
+
+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.
+```
+
+##### `post_app_clearaccess`
+
+```bash
+app_id=$1
+```
+
+##### `post_cert_update`
+```bash
+domain=$1
+```
+
+The rest of the script depends on what you want to do in it.
+
+### `conf_regen` special case 
+The `conf_regen` hook is a more delicate hook, either for its implementation or for its content.
+
+##### `conf_regen` hook setup
+
+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
+```
+
+> When removing the application, this hook must be removed manually.
+
+##### Building `conf_regen` hook script
+
+`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.
+
+`conf_regen` hook script should look like this:
+
+```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
+```

packaging_apps_hooks_fr.md

@@ -27,18 +27,18 @@ 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
+Après l'installation d'une application.
 - `post_app_upgrade`
-Après l'upgrade d'une applications
+Après l'upgrade d'une applications.
 - `post_app_remove`
-Après la supression d'une applications
+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
+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
+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:
+Services pris en charge par `regen-conf` :
  - avahi-daemon
  - dnsmasq
  - dovecot
@@ -57,14 +57,14 @@ Services pris en charge par regen-conf:
 
 ### Mise en place des hooks
 
-A l'exception du hook conf_regen, tout les hooks s'utilisent de la même manière.  
+À 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.
+> 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 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
@@ -103,7 +103,7 @@ purge=$2  # True/False Indique si le dossier utilisateur a été supprimé ou pa
 ##### `post_iptable_rules`
 
 ```bash
-upnp=$1  # True/False Indique si l'upnp est activé ou non.
+upnp=$1  # True/False Indique si l'UPnP est activé ou non.
 ipv6=$2  # True/False Indique si l'IPV6 est activé ou non.
 ```
 
@@ -118,7 +118,7 @@ backup_name=$1
 Les variables utilisables dans ces scripts sont les mêmes que celles disponibles dans [les scripts d'actions associés](/packaging_apps_scripts).
 
 
-Example: pour `post_app_install` les variables sont les mêmes que pour le script `install`
+Example : pour `post_app_install` les variables sont les mêmes que pour le script `install`
 
 ##### `post_app_addaccess` et `post_app_removeaccess`
 
@@ -141,11 +141,11 @@ 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.
+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.  
+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
@@ -155,9 +155,9 @@ cp hook_regen_conf /usr/share/yunohost/hooks/conf_regen/50-SERVICE_$app
 
 ##### 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 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:
+Un script de hook `conf_regen` devrait donc ressembler à ça :
 
 ```bash
 #!/bin/bash