Configuration

La configuration rassemble vos services de notification, tags et groupes dans un seul fichier. Elle évite aussi d’inscrire vos identifiants dans l’historique du 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

Priorité des Paramètres en Configuration TEXT

Pour les URL TEXT et celles transmises directement à la CLI ou à la bibliothèque Python, les valeurs suivent cet ordre :

1. Paramètres de requête (?clé=valeur) — ont la priorité sur les valeurs du chemin URL, y compris les alias (ex. ?pass= est traité comme ?password=).
2. Valeurs du chemin URL (plus bas) — identifiants et hôte extraits directement de la chaîne URL (ex. user:pass@host:port).

En YAML, les réglages placés sous une URL ont la priorité sur les deux.

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

Placez les services de notification dans la liste urls.

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

YAML vs TEXT pour les Paramètres Complexes

Avec YAML, vous pouvez écrire les réglages sous l’URL. Les mots de passe et autres valeurs contenant des espaces ou des caractères comme @ et # s’écrivent alors normalement. Dans une URL, ces caractères nécessitent un encodage.

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 et 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 suivent une priorité à trois niveaux. Le niveau le plus haut l’emporte lorsque le même champ est défini par plusieurs sources :

1. Sous-clés YAML (le plus haut) : remplacent toujours tout le reste.
2. Paramètres de requête de l’URL (ex. ?smtp=..., ?user=abc) : remplacent les valeurs du chemin d’URL.
3. Valeurs du chemin d’URL (le plus bas) : user, password, host et port extraits de l’URL elle-même (ex. user:pass@host:port).

Les composants courants d’une URL, comme user, password, host, port et verify, peuvent être fournis comme sous-clés. Il en va de même pour les paramètres propres au service qui figurent dans le tableau ## Détail des Paramètres du plugin, y compris les éléments nommés de l’URL comme le botname: de Discord.

Note

Certains raccourcis représentent plusieurs valeurs d’URL. Par exemple, le token: de Slack peut représenter un jeton de bot ou trois jetons de webhook. Conservez ces raccourcis dans l’URL ; utilisés comme sous-clés, ils sont ignorés et un avertissement est consigné dans le journal.

Le service Email ci-dessus en est un exemple. Dans l’exemple XMPP suivant, les identifiants et options sont aussi placés sous l’URL. Le réglage host: remplace l’hôte indiqué 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

Formes d’Entrée YAML pour les URLs

Une entrée urls: peut prendre quatre formes distinctes. Chaque forme contrôle le nombre d’instances de service créées et la façon dont les valeurs des paramètres sont appliquées.

Instance Unique

La forme la plus courante : une entrée URL crée une instance de service. Les clés de tokens correspondent directement aux paramètres du plugin et remplacent toute valeur déjà présente dans l’URL.

Les tokens peuvent être écrits soit indentés d’un niveau sous la clé d’URL (forme enfant, imbrication YAML standard) soit au même niveau d’indentation que la clé d’URL (forme voisine). Les deux produisent des résultats identiques.

Forme enfant :

urls:
  - mailtos://smtp.example.com:
      user: sender@example.com
      password: "myP@ss#w0rd!"
      to: recipient@example.com

Forme voisine (équivalente) :

urls:
  - mailtos://smtp.example.com:
    user: sender@example.com
    password: "myP@ss#w0rd!"
    to: recipient@example.com

Lorsque tous les identifiants sont fournis sous forme de tokens YAML, il suffit d’omettre les identifiants de l’URL — un simple schema:// suffit :

urls:
  - mailtos://:
    user: sender@example.com
    password: "myP@ss#w0rd!"
    smtp: smtp.example.com
    from: sender@example.com
    to: recipient@example.com

Note

L’ancienne forme mailtos://_: (avec un placeholder _) est toujours acceptée et produit le même résultat. Les deux styles fonctionnent.

Note

Dans les blocs de tokens YAML, password: et pass: sont tous deux acceptés — pass: est automatiquement normalisé en password: par Apprise. Lorsque les deux clés apparaissent dans le même bloc, password: a la priorité.

Cibles Multiples

Lorsqu’un paramètre de plugin accepte plusieurs valeurs (comme to: pour plusieurs destinataires), fournissez-les sous forme de chaîne séparée par des virgules ou de liste YAML sous cette clé. Dans les deux cas, une seule instance de service est créée avec toutes les valeurs dans sa liste de cibles — ce n’est pas la même chose que créer plusieurs instances.

Séparé par des virgules (équivalent à ?to=user1,user2 dans l’URL) :

urls:
  - mailtos://smtp.example.com:
      user: sender@example.com
      password: secret
      to: user1@example.com, user2@example.com

Liste YAML (même résultat, plus lisible pour les longues listes) :

urls:
  - mailtos://smtp.example.com:
      user: sender@example.com
      password: secret
      to:
        - user1@example.com
        - user2@example.com

La même syntaxe s’applique à tag: et à tout autre paramètre de type liste.

Instances Multiples

Lorsque la valeur enfant d’une clé d’URL est une liste YAML, Apprise crée une instance de service par entrée de la liste. Les tokens de chaque entrée remplacent les valeurs de l’URL de façon indépendante — les entrées n’héritent pas des tokens des autres entrées.

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

Ceci charge deux services mailto://. Les deux héritent de user:pass@gmail.com depuis l’URL. Chaque instance reçoit ses propres to et tag ; aucune ne voit les valeurs de l’autre entrée.

Attention

Pour créer plusieurs instances, la liste doit être indentée en tant qu’enfant de la clé d’URL (un niveau plus profond), et non au même niveau. Pour plusieurs cibles d’une instance unique, utilisez plutôt la forme séparée par des virgules ou la liste YAML sous la clé, présentées dans l’onglet “Cibles Multiples”.

Instances Multiples + Tokens Partagés

Combinez une liste indentée en enfant (une instance par entrée) avec des tokens voisins (au même niveau d’indentation que la clé d’URL) pour partager des paramètres entre toutes les instances générées.

Les tokens par entrée ont la priorité sur les tokens voisins pour toute clé que les deux définissent.

urls:
  - mailtos://smtp.example.com:
      - to: manager@example.com
        tag: boss
      - to: coworker@example.com
        tag: new-hire
    user: sender@example.com
    password: shared_secret

Ceci crée deux instances mailtos://. Les tokens voisins user: et password: sont appliqués aux deux. Les to: et tag: propres à chaque entrée sont spécifiques à l’instance et remplacent toute valeur voisine pour la même clé.

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 indentée sous une clé d’URL crée une instance de service par entrée. Le détail complet est présenté dans les onglets Instances Multiples et Instances Multiples + Tokens Partagés ci-dessus.

Attention

Un tiret - mal placé peut silencieusement diviser une entrée en plusieurs instances indépendantes, chacune ne recevant qu’une partie des paramètres souhaités.

# Intention : une instance avec deux cibles
urls:
  - schema://host:
      to: user1@example.com, user2@example.com  # correct : une instance

# Accidentel : deux instances indépendantes, chacune sans la config de l'autre
urls:
  - schema://host:
      - to: user1@example.com   # instance 1 -- ne voit que ses propres clés
      - to: user2@example.com   # instance 2 -- ne voit que ses propres clés

Cette division est intentionnelle et utile lorsque des instances différentes ont vraiment besoin de paramètres distincts. Mais si l’objectif est une instance unique avec plusieurs cibles, utilisez plutôt une valeur séparée par des virgules ou une liste YAML sous la clé.

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.

La langue utilisée par Apprise pour ses propres textes peut être définie sous asset via language (ou lang), par exemple language: fr. Omettez-la pour suivre la langue de l’ordinateur sur lequel Apprise s’exécute.

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.

Variables de substitution

Une configuration YAML peut déclarer des valeurs ${NOM} à fournir plus tard :

template:
  recipient:

urls:
  - mailtos://user:password@example.com/:
      - to: ${RECIPIENT}

Seuls les noms déclarés sous template: sont remplacés. Une variable ne peut définir ni tag:, ni tags:, ni le nom du service avant ://. Consultez Variables de substitution pour les règles et les exemples de la CLI, de l’API et de l’environnement.

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>