Configuration

La configuration permet de définir tous vos services de notification au même endroit, tout en prenant en charge les groupes, les tags et la protection des secrets hors de l’historique de votre shell.

La configuration Apprise est portable. Le même fichier de configuration peut être utilisé sans modification avec le CLI, le serveur API et la bibliothèque Python.

Envisagez d’utiliser des fichiers de configuration si :

• vous souhaitez réutiliser la même configuration de notification sur plusieurs scripts ou systèmes ;
• vous voulez garder les identifiants hors de l’historique de votre shell ;
• vous voulez regrouper des services ou simplifier les références à vos URL Apprise à l’aide de tags ;
• vous voulez que la même configuration fonctionne avec le CLI, l’API et Python.

Si vous n’avez besoin que d’une notification ponctuelle, des URL en ligne suffisent. Pour tout ce qui va au-delà, les fichiers de configuration sont recommandés.

Formats de Configuration Pris en Charge

Apprise prend en charge deux formats de configuration. Tous deux décrivent les mêmes informations, mais YAML permet d’exprimer davantage de structure.

• TEXT : simple, basé sur des lignes et facile à lire. Idéal pour les petites configurations ou les réglages manuels.
• YAML : structuré et normalisé. Mieux adapté aux configurations plus volumineuses et aux outils d’automatisation.

TEXT

Configuration TEXT

La configuration TEXT est basée sur des lignes.

• Les lignes vides sont ignorées
• Les commentaires commencent par # ou ;
• Chaque URL peut être précédée d’un ou plusieurs tags
• Vous pouvez définir des groupes de tags
• Vous pouvez inclure d’autres sources de configuration

La configuration TEXT est idéale si :

• vous voulez la configuration la plus simple possible ;
• vous ne gérez qu’un petit nombre de services ;
• vous préférez une syntaxe minimale.

Syntaxe TEXT de Base

# Notifications email
mailto://user:password@gmail.com

# Notifications Discord
discord://webhook_id/webhook_token

Tags et Groupement en TEXT

Les tags vous permettent d’organiser vos services de notification en groupes logiques tels que personal, ops ou critical. Vous pouvez ensuite cibler ces groupes sans modifier vos URL de destination.

Exemples de Tags en TEXT

Vous pouvez catégoriser les services en plaçant des tags avant l’URL, séparés par un signe égal (=).

# Syntaxe : tag=url
# Associe le tag 'desktop' à cette notification
desktop=gnome://

# Vous pouvez attribuer plusieurs tags en utilisant des virgules ou des espaces
# Cette URL fait partie de 'tv' ET de 'kitchen'
tv,kitchen=kodi://user:pass@kitchen.host

Regrouper des Tags avec une Configuration TEXT

Vous pouvez inclure d’autres fichiers de configuration afin de garder votre configuration propre. C’est excellent pour séparer les secrets de la logique générale.

# 1. Définir vos services de base
user1=mailto://credentials
user2=mailto://credentials

# 2. Définir un groupe
# Notifier 'friends' notifiera 'user1' et 'user2'
friends = user1, user2

Includes TEXT

Vous pouvez importer d’autres fichiers de configuration (locaux ou distants) à l’aide du mot-clé include.

# Lire depuis un autre fichier de configuration Apprise sur le serveur local
include /etc/apprise/secrets.conf

# Lire depuis un serveur API Apprise
include https://my-config-server.com/get/my-key/

Note

Le serveur API Apprise n’autorisera pas l’utilisation de include pour des fichiers stockés localement sur le serveur pour des raisons de sécurité.

YAML

Configuration YAML

La configuration YAML est structurée et convient mieux aux installations plus importantes. Elle fournit aussi une configuration asset optionnelle (image de marque et valeurs par défaut), indisponible avec le format TEXT.

Syntaxe YAML de Base

Tous les services sont listés sous une liste urls.

urls:
  - json://localhost
  - slack://tokenA/tokenB/tokenC

YAML vs TEXT pour les Paramètres Complexes

L’un des avantages les plus pratiques de YAML par rapport au TEXT est que les paramètres peuvent être sortis de l’URL et écrits comme des valeurs YAML normales. Dans une URL brute, toute valeur contenant des caractères spéciaux — espaces, @, #, chevrons — doit être encodée en pourcentage avant de pouvoir figurer dans l’URL. En YAML, ces mêmes valeurs peuvent être écrites comme des chaînes ordinaires sans encodage URL.

Prenons l’exemple d’une URL SMTP avec un mot de passe complexe, une adresse d’expéditeur incluant un nom d’affichage, et un chemin vers une clé PGP privée :

Sous forme d’URL unique (format TEXT ou argument CLI) :

mailtos://joe:myP%40ss%23w0rd%21@example.com?smtp=smtp.example.com&from=Joe+User%3Cjoe%40example.com%3E&pgp=sign&pgpprv=%2Fhome%2Fjoe%2FMes+Cles%2Fprivate.asc

En YAML — sans encodage, immédiatement lisible :

urls:
  - mailtos://example.com:
      password: "myP@ss#w0rd!"
      smtp: smtp.example.com
      from: "Joe User <joe@example.com>"
      pgp: sign
      pgpprv: "/home/joe/Mes Clés/private.asc"

Les sous-clés YAML ont toujours la priorité sur les valeurs extraites de l’URL. Lorsque le même champ est défini à la fois dans l’URL et en tant que sous-clé YAML, c’est la sous-clé qui l’emporte — que ce soit face aux composantes structurelles de l’URL (user:pass@host) ou aux paramètres de requête déjà présents dans l’URL (?user=abc&password=123). Tous les composants courants d’une URL — user, password, host, port et verify — ainsi que chaque paramètre propre au service figurant dans le tableau ## Détail des Paramètres du plugin peuvent être fournis en tant que sous-clés.

Cela signifie que l’URL elle-même peut se réduire au strict minimum — le schéma seul — avec tous les identifiants et options dans le bloc YAML, sans aucun encodage URL nulle part. Le service Email est illustré ci-dessus, mais la même approche fonctionne pour n’importe quel service Apprise.

Le même modèle fonctionne pour n’importe quel service. L’exemple XMPP ci-dessous conserve une URL minimale — la sous-clé host: remplace le nom d’hôte extrait de l’URL, tandis que user: et password: fournissent des identifiants qui n’étaient pas dans l’URL :

urls:
  - xmpp://chat.example.com:
      user: alerts@example.com
      password: "correct horse battery staple"
      host: xmpp.example.com
      verify: yes
      to: ops-room@example.com

Tags et Groupement en YAML

Les tags vous permettent d’organiser vos services de notification en groupes logiques tels que personal, ops ou critical. Vous pouvez ensuite cibler ces groupes sans modifier vos URL de destination.

Exemples de Tags en YAML

Attribuer un tag :

version: 1
urls:
  - discord://webhook_id/webhook_token:
      tag: ops

Attribuer plusieurs tags :

version: 1
urls:
  - mailto://user:password@gmail.com:
      tag:
        - personal
        - after-hours

Réutiliser une URL avec Plusieurs Entrées YAML

Une liste YAML placée sous une URL crée une définition de service pour chaque élément de la liste. Apprise part de la même URL analysée à chaque fois, puis applique les valeurs YAML de cet élément comme remplacements.

C’est utile lorsque plusieurs destinations partagent les mêmes identifiants mais ont besoin de cibles, tags ou options différents :

version: 1
urls:
  - mailto://user:pass@gmail.com:
      - to: manager@example.com
        tag: boss
      - to: coworker@example.com
        tag: new-hire

L’exemple ci-dessus charge deux services mailto://. Les deux héritent de user:pass@gmail.com depuis l’URL, tandis que chaque entrée reçoit ses propres valeurs to et tag.

Regrouper des Tags avec une Configuration YAML

Vous pouvez appliquer des tags à chaque URL d’un fichier en utilisant tag (ou tags) à la racine :

version: 1
tag: org-default

urls:
  - discord://webhook_id/webhook_token
  - mailto://user:password@gmail.com

Vous pouvez aussi taguer individuellement vos URL Apprise avec le même identifiant :

version: 1

urls:
  - discord://webhook_id/webhook_token:
      tag: ops
  - slack://token_a/token_b/token_c:
      tag: ops
  - mailto://user:password@gmail.com:
      tag: ops

Vous pouvez également utiliser la directive groups pour créer de nouveaux identifiants de tags et indiquer quels tags existants ils englobent.

version: 1

groups:
  critical: ops, after-hours

urls:
  - discord://webhook_id/webhook_token:
      tag: ops

  - mailto://user:password@gmail.com:
      tag: after-hours

Configuration des Assets

La configuration des assets vous permet d’ajuster les valeurs par défaut et l’image de marque. En pratique, vous pouvez remplacer l’identité visuelle par défaut d’Apprise (icônes, App ID) envoyée au service amont.

Note

L’image de marque n’est disponible qu’avec la configuration YAML.

Les clés d’asset suivent quelques règles :

• les clés qui commencent par _ ou se terminent par _ sont ignorées ;
• seules les clés d’asset déjà existantes, de type chaîne ou booléen, peuvent être définies ;
• les valeurs doivent être des chaînes ou des booléens ; les chaînes sont converties en booléens lorsque la valeur par défaut sous-jacente est booléenne.

Un sous-ensemble pratique de clés couramment utilisées est présenté ci-dessous ; si vous ne remplacez pas une entrée, sa valeur par défaut est conservée.

version: 1

asset:
  #
  # Image de marque
  #

  # Un identifiant court pour décrire l'application
  app_id: Apprise
  # Une description par défaut de la notification (utilisée par certains services amont)
  app_desc: Apprise Notifications
  # Où obtenir plus d'informations sur votre application ?
  app_url: https://github.com/caronc/apprise

  #
  # Comportements par défaut
  #

  # les notifications sont émises séquentiellement si la valeur est false (par défaut = true)
  async_mode: true

  # Convertir \r ou \n en véritables caractères <CR> et <LF> lors du traitement du corps
  # (par défaut = false)
  interpret_escapes: false

  # les identifiants sont protégés lorsqu'ils sont écrits dans les journaux (par défaut = true)
  secure_logging: true

  # Encodage utilisé lors de la lecture de la configuration sur disque
  encoding: utf-8

  #
  # Thèmes
  #

  # Thème par défaut utilisé lors de la résolution des icônes
  theme: default

  # Remplacement optionnel des chemins d'URL d'icônes (avancé)
  # Les valeurs par défaut sont récupérées depuis :
  #   http://github.com/caronc/apprise/tree/master/apprise/assets/themes/default
  image_url_mask: https://example.local/assets/themes/{THEME}/apprise-{TYPE}-{XY}{EXTENSION}
  image_url_logo: https://example.local/assets/themes/{THEME}/apprise-logo.png
  image_path_mask: /apprise/installation/assets/themes/{THEME}/apprise-{TYPE}-{XY}{EXTENSION}

  # Indiquez à Apprise à l'avance quel type de contenu vous allez lui fournir ;
  # Les valeurs sont :
  #   - null: (par défaut) transmet le contenu tel quel
  #   - "text": le contenu fourni est au format "text" (valeur par défaut pour le CLI)
  #   - "html": le contenu fourni est en HTML
  #   - "markdown": le contenu fourni est au format Markdown
  body_format: null

urls:
  - discord://webhook_id/webhook_token:
      tag: ops

  - mailto://user:password@gmail.com:
      tag: after-hours

Le fuseau horaire peut également être défini sous asset via timezone (ou tz) afin de contrôler le fuseau horaire par défaut utilisé par Apprise.

Groupement

YAML permet des définitions de groupes récursives (des groupes contenant d’autres groupes).

groups:
  - finance: user1, user2
  - devteam: user3, user4
  # Groupe récursif
  - company: finance, devteam, boss

urls:
  - mailto://credentials:
      - tag: user1

Includes YAML

Vous pouvez importer d’autres configurations en utilisant la section optionnelle include:

include:
  # Lire depuis un autre fichier de configuration Apprise sur le serveur local
  - /etc/apprise/secrets.yml
  # Lire depuis un serveur API Apprise
  - https://my-config-server.com/get/my-key/

Note

Vous ne pouvez pas configurer le serveur API Apprise pour inclure un fichier local.

Cibler des Tags lors de l’Envoi

Le filtrage par tag reste cohérent entre les outils. Par exemple, avec le CLI vous pouvez cibler un groupe via son tag :

Les expressions de filtre générales suivent ces règles :

Filtre	Services sélectionnés
--tag TagA	Possède TagA
--tag TagA,TagB	Possède TagA ET TagB
--tag 'TagA' --tag 'TagB	Possède TagA OU TagB
--tag 'TagA,TagC --tag TagB	Possède (TagA ET TagC) OU TagB

Note

Lorsque vous utilisez une virgule, vous appliquez un filtre : vous demandez à Apprise de restreindre la liste aux seuls services possédant tous les tags indiqués. Pour élargir la liste et inclure plusieurs groupes différents, répétez simplement l’option --tag (-g).

Exemple :

apprise --tag="ops,critical" \
   --body="Notifier les services qui possèdent à la fois les tags ops ET critical"

apprise --tag="ops" --tag "critical" \
   --body="Notifier tous les services qui possèdent soit 'ops', soit 'critical', soit les deux"

Charger une Configuration

Que vous utilisiez TEXT ou YAML, le chargement de la configuration dans le CLI ou la bibliothèque se fait de la même manière.

Utilisation CLI

Vous pouvez charger un fichier avec l’option --config (ou -c). Vous pouvez la préciser plusieurs fois pour charger plusieurs fichiers.

# Charger un fichier local
apprise --config=/etc/apprise/config.yml --body="test"

# Charger depuis une URL
apprise --config=https://myserver.com/cfg/apprise --body="test"

Emplacements de Configuration par Défaut

Si vous ne précisez aucun fichier de configuration via le CLI (--config), Apprise charge automatiquement un fichier de configuration par défaut pour vous.

Linux/BSD/Apple

Les fichiers de configuration suivants sont recherchés dans l’ordre indiqué ci-dessous ; la première correspondance trouvée est chargée, et rien d’autre n’est ensuite traité.

1. ~/.apprise
2. ~/.apprise.conf
3. ~/.apprise.yml
4. ~/.apprise.yaml
5. ~/.config/apprise
6. ~/.config/apprise.conf
7. ~/.config/apprise.yml
8. ~/.config/apprise.yaml
9. ~/.apprise/apprise
10. ~/.apprise/apprise.conf
11. ~/.apprise/apprise.yml
12. ~/.apprise/apprise.yaml
13. ~/.config/apprise/apprise
14. ~/.config/apprise/apprise.conf
15. ~/.config/apprise/apprise.yml
16. ~/.config/apprise/apprise.yaml

Les chemins globaux suivants sont aussi recherchés si rien n’est trouvé ci-dessus :

1. /etc/apprise
2. /etc/apprise.yml
3. /etc/apprise.yaml
4. /etc/apprise/apprise
5. /etc/apprise/apprise.conf
6. /etc/apprise/apprise.yml
7. /etc/apprise/apprise.yaml

Microsoft Windows

Les fichiers de configuration suivants sont recherchés dans l’ordre indiqué ci-dessous ; la première correspondance trouvée est chargée, et rien d’autre n’est ensuite traité.

1. %APPDATA%\Apprise\apprise
2. %APPDATA%\Apprise\apprise.conf
3. %APPDATA%\Apprise\apprise.yml
4. %APPDATA%\Apprise\apprise.yaml
5. %LOCALAPPDATA%\Apprise\apprise
6. %LOCALAPPDATA%\Apprise\apprise.conf
7. %LOCALAPPDATA%\Apprise\apprise.yml
8. %LOCALAPPDATA%\Apprise\apprise.yaml

Les chemins globaux suivants sont aussi recherchés si rien n’est trouvé ci-dessus :

1. %ALLUSERSPROFILE%\Apprise\apprise
2. %ALLUSERSPROFILE%\Apprise\apprise.conf
3. %ALLUSERSPROFILE%\Apprise\apprise.yml
4. %ALLUSERSPROFILE%\Apprise\apprise.yaml
5. %PROGRAMFILES%\Apprise\apprise
6. %PROGRAMFILES%\Apprise\apprise.conf
7. %PROGRAMFILES%\Apprise\apprise.yml
8. %PROGRAMFILES%\Apprise\apprise.yaml
9. %COMMONPROGRAMFILES%\Apprise\apprise
10. %COMMONPROGRAMFILES%\Apprise\apprise.conf
11. %COMMONPROGRAMFILES%\Apprise\apprise.yml
12. %COMMONPROGRAMFILES%\Apprise\apprise.yaml

En supposant que l’utilisateur soit foobar et que Microsoft Windows soit installé sur le lecteur C:\, cela peut être interprété comme suit :

Variable d’environnement	Exemple de traduction
%APPDATA%	C:\Users\foobar\AppData\Roaming
%LOCALAPPDATA%	C:\Users\foobar\AppData\Local
%ALLUSERSPROFILE%	C:\ProgramData
%PROGRAMFILES%	C:\Program Files
%COMMONPROGRAMFILES	C:\Program Files\Common Files

Le saviez-vous ?

Apprise détermine automatiquement le format (TEXT ou YAML) à partir de l’extension du fichier (.yml ou .yaml). Si votre fichier n’a pas d’extension, il est traité comme du TEXT par défaut, sauf si une structure YAML valide est détectée.

Tags Réservés

Il existe deux tags spéciaux que vous pouvez utiliser pour contrôler le comportement des notifications.

Tag	Description
always	Si vous attribuez le tag always à une URL dans votre configuration, elle sera TOUJOURS déclenchée, même si vous filtrez sur un autre tag via le CLI.
all	Utilisé lors de l’envoi d’une notification (par exemple apprise --tag=all). Cela demande à Apprise d’ignorer tous les filtres et de notifier tous les services définis.

Pour les fonctionnalités avancées de tags — chaînes d’escalade par priorité, filtrage exclusif, tentatives/délai par service et remplacements par appel — consultez Routage par Tags & Tentatives.

Configuration Web Hébergée en Privé

Si vous hébergez votre configuration sur un serveur web privé, Apprise détecte le format en fonction de l’en-tête Content-Type renvoyé par le serveur, ou via un paramètre d’URL explicite.

Format	HTTP Content-Type	Forçage par URL
YAML	text/yaml, application/x-yaml	http://...?format=yaml
TEXT	text/plain	http://...?format=text

Note

Si vous utilisez une instance de l’API Apprise, vos URL include ressemblent à ceci : http://apprise-host/get/<key>