Aller au contenu

Configuration

Le fichier de configuration décrit tout le bot : la connexion Telegram, les personnes autorisées, le menu de boutons et les journaux. Transmettez-le avec --config aux commandes run, validate, fmt et list-functions (voir CLI).

Toutes les clés utilisent lower_snake_case. Les clés inconnues sont refusées : une faute est immédiatement signalée par la validation.

Obligatoire signifie que la validation échoue si le champ manque ou reste vide après application des valeurs par défaut.
Les champs facultatifs peuvent être omis ; la colonne Par défaut indique la valeur alors utilisée.

Si vous débutez, commencez par Exécuter dans la CLI, qui crée une première configuration. Consultez Concepts pour le vocabulaire.

Configuration minimale

Seuls telegram, avec un jeton et un utilisateur autorisé, et menu sont obligatoires. Tous les autres champs ont une valeur par défaut :

Commencer avec un utilisateur et trois boutons d’état

config.yaml (minimal)
telegram:
  bot_token: "YOUR_BOT_TOKEN"
  allowed_users:
    - "123456789"

menu:
  - name: System Status
    type: category
    icon: "🖥️"
    items:
      - name: Uptime
        type: button
        icon: "🕒"
        function: command
        command: "uptime"
      - name: Memory
        type: button
        icon: "🧮"
        function: command
        command: "free -h"
      - name: Disk Space
        type: button
        icon: "💾"
        function: command
        command: "df -h /"

Le dossier config-examples/ de la version contient un exemple minimal et un complet.

Champs racine

Champ Type Obligatoire Par défaut Description
telegram objet oui — Réglages Telegram (voir ci-dessous)
menu liste oui — Arborescence du menu, au moins un élément
function_directory chaîne non non défini Dossier YAML des fonctions personnalisées (voir les règles ci-dessous)
shell chaîne non /bin/bash Shell utilisé comme shell -c "<command>"
timeout durée non 60s Délai maximal par défaut d’une commande
max_output_bytes entier non 524288 Sortie maximale conservée par commande (voir Quantité de sortie affichée et Contrôler la sortie)
output auto | text | file non auto Comment le résultat de la commande est livré (voir Quantité de sortie affichée et Contrôler la sortie)
max_output_messages entier non 2 Uniquement à la racine. En mode auto, envoyer un fichier .txt lorsque le résultat dépasserait ce nombre de messages (1–10). Omettez-le pour garder 2. Consultez Contrôler la sortie
workdir chaîne non dossier du processus Dossier de travail par défaut
env objet non vide Variables d’environnement supplémentaires
menu_columns entier non 2 Boutons d’élément par ligne sous la zone de message
page_size entier non 8 Éléments par page avant pagination
confirm_ttl durée non 5m Durée de validité d’une confirmation
delivery_retry_backoff durée non 1s Racine uniquement. Attente initiale avant la première nouvelle tentative après un envoi en échec. Voir Nouvelles tentatives d’envoi
delivery_retry_backoff_max durée non 30s Racine uniquement. Attente maximale entre les tentatives. Voir Nouvelles tentatives d’envoi
delivery_retry_ttl durée non 2m Racine uniquement. Durée totale pendant laquelle le bot continue d’essayer avant d’abandonner (uniquement noté dans le journal serveur). Voir Nouvelles tentatives d’envoi
enable_run_command booléen non false Affiche $ >_ Run Command pour exécuter le message suivant comme commande shell. Cette option est désactivée par défaut. Toute personne autorisée peut alors exécuter n’importe quelle commande sur l’hôte : activez-la uniquement si vous faites confiance à tous les utilisateurs autorisés. Cette clé est invalide sous telegram.
logging objet non journal par défaut Journaux nommés (voir ci-dessous)
Que se passe-t-il si shell est omis ?

Le bot utilise /bin/bash. Les autres champs racine facultatifs utilisent également leur valeur par défaut. Définissez-les uniquement pour utiliser une autre valeur, par exemple shell: /bin/sh.

Quantité de sortie affichée

Deux limites s’appliquent successivement. max_output_bytes est votre limite, en plus d’une limite Telegram que vous ne pouvez pas changer.

1. Votre limite : max_output_bytes (524288 par défaut, soit 512 Ko)

Pendant qu’une commande tourne, le bot conserve au plus cette quantité de sortie, comptée séparément pour la sortie normale et les erreurs. Au-delà, le reste est jeté, mais la commande continue jusqu’à la fin ou son timeout. Le résultat commence alors par (output truncated).

2. Livraison du résultat : output (auto par défaut)

Telegram autorise au plus 4096 octets par message. Le bot peut découper un long résultat en plusieurs messages de réponse, ou envoyer toute la sortie comme fichier .txt. Choisissez le mode avec output à la racine, ou remplacez-le sur un bouton :

Valeur Comportement
auto Messages texte tant que le résultat tient dans max_output_messages messages (défaut 2). S’il en faudrait plus, envoi d’un fichier .txt.
text Toujours découper en messages texte. S’arrête toujours après 10 messages et signale la coupure.
file Toujours envoyer un fichier .txt avec une légende courte (nom du bouton, code de sortie, durée).

En modes auto et file, le fichier contient l’en-tête plus stdout et stderr : augmenter max_output_bytes livre vraiment plus de sortie. Si l’envoi du fichier échoue, le bot réessaie automatiquement et ne repasse par les messages texte qu’après avoir abandonné. Voir Nouvelles tentatives d’envoi.

Vous n’avez pas à écrire output ni max_output_messages. Si vous les omettez, le bot utilise auto et 2. Un fichier déjà valide reste inchangé. max_output_messages n’existe qu’à la racine. Sur un bouton, omettez output pour utiliser la valeur racine ; ne le mettez que si ce bouton doit toujours envoyer un fichier ou rester en texte.

Pour les longs journaux, préférez output: auto (défaut) ou output: file sur ce bouton. Vous pouvez aussi raccourcir la commande si seule une fin de journal suffit.

Pour aller plus loin : Contrôler la sortie

Une page entière est consacrée à ces trois champs. Elle parcourt chaque combinaison racine et bouton, une par une, et montre pour chacune une image de la conversation Telegram.

Lire Contrôler la sortie

Règles de function_directory

Situation Résultat
Clé absente Journal d’information ; fonctions intégrées uniquement
Clé présente mais vide ("") Journal d’information ; fonctions intégrées uniquement
Chemin absent ou inaccessible Erreur bloquante ; arrêt du processus
Dossier existant mais vide Valide

Un chemin incorrect arrête le bot

Si function_directory indique un dossier absent ou illisible, le programme s’arrête au lieu de démarrer sans vos fonctions personnalisées.

telegram

Champ Type Obligatoire Par défaut Description
bot_token chaîne oui — Jeton du bot fourni par BotFather
allowed_users liste de chaînes oui — Utilisateurs autorisés
api chaîne non https://api.telegram.org URL de base de l’API du bot
proxy.enabled booléen non false Utiliser un proxy pour Telegram
proxy.url chaîne conditionnel — Obligatoire si proxy.enabled vaut true
insecure booléen non false Ignorer la vérification TLS (déconseillé)

Les utilisateurs non autorisés reçoivent leur user_id et leur username afin de demander l’accès. C’est aussi ainsi que vous trouvez votre propre identifiant la première fois ; consultez Exécuter dans la CLI → Étape 5.

Se connecter avec un proxy

section telegram avec un proxy
telegram:
  bot_token: "123456789:AAExampleTokenValue"
  allowed_users:
    - "123456789"        # identifiant numérique de l’utilisateur
    - "@alice"           # ou un nom d’utilisateur
  proxy:
    enabled: true
    url: "socks5://127.0.0.1:10808"

Pour permettre les commandes shell saisies dans Telegram, ajoutez ce réglage à la racine du fichier, pas sous telegram :

Ajouter un réglage racine

Activer le bouton Run Command
enable_run_command: true

Cette section référence les champs. Pour une explication guidée, consultez Menu. Chaque bouton ou catégorie accepte :

Champ Type Obligatoire Description
name chaîne oui Nom affiché, unique parmi les voisins sans tenir compte de la casse
type category | button oui Type d’élément
items liste si category Enfants, au moins un
function chaîne si button Nom de la fonction
command chaîne si function: command Commande shell intégrée
path chaîne si function: script Chemin du script
icon chaîne non Emoji facultatif
id chaîne non Identifiant facultatif pour cet élément ; vous pouvez l’omettre
confirm booléen non Demander une confirmation, false par défaut
timeout durée non Remplace le délai global
workdir chaîne non Remplace le dossier de travail
env objet non Variables d’environnement du bouton
columns entier non Remplace le nombre de colonnes de la catégorie
output auto | text | file non Facultatif. Omettez-le pour utiliser le output racine. Ne le mettez que pour forcer ce bouton en file ou text (voir Quantité de sortie affichée et Contrôler la sortie)
args chaîne non Arguments facultatifs de script
Tout nom de paramètre déclaré scalaire selon la fonction Valeur transmise, par exemple url, host, unit ou lines

Sur un bouton, toute autre clé scalaire est un paramètre de fonction. Son nom doit être déclaré par la fonction. validate refuse les noms inconnus et vérifie les valeurs int et bool. Les chaînes, nombres et booléens s’écrivent directement en YAML.

Sur une catégorie, toute clé extérieure aux champs ci-dessus est une erreur. Les catégories n’exécutent pas de fonction et ne peuvent donc pas contenir de paramètres.

command, path et args remplissent les paramètres de même nom. Écrivez les autres paramètres directement sur le bouton, sans bloc params:. Consultez Fonctions → Transmettre des valeurs.

logging

Facultatif. Sans réglage, un journal console sur stderr au niveau info est utilisé.

Écrire les journaux normaux et un fichier d’audit

section logging avec un fichier d’audit
logging:
  logs:
    default:
      level: info
      format: console   # ou JSON
      output:
        - output: stderr
    audit:
      level: info
      format: json
      output:
        - output: file
          file: /var/log/telegram-commander/audit.log

Sorties prises en charge : stdout, stderr, file, discard.

Le journal audit enregistre chaque commande, la personne, le bouton, le code de sortie et la durée. Consultez Journal d’audit.

Pages associées