Schaltfläche¶

Ein antippbarer Eintrag im Telegram-Menü. Eine Schaltfläche besitzt einen name und führt beim Antippen eine Funktion auf Ihrem Server aus. Das Ergebnis wird an den Chat zurückgesendet.

Schaltflächen und Kategorien bilden gemeinsam den Menü-Baum unter dem obersten Schlüssel menu in Ihrer Konfigurationsdatei. Eine Schaltfläche erledigt die Arbeit; eine Kategorie öffnet nur ein Untermenü.

Darstellung einer Schaltfläche¶

Schaltflächen erscheinen auf der Tastatur unter dem Nachrichtenfeld, standardmäßig zwei pro Zeile. Der von Ihnen gewählte Name ist der Text auf der Taste. Halten Sie ihn kurz genug, damit er auf einem Smartphone lesbar bleibt. Siehe Menü → Darstellung des Telegram-Menüs.

Bestandteile einer Schaltfläche¶

Jede Zeile steuert einen Bestandteil der Schaltfläche

Eine vollständig beschriftete Schaltfläche

- name: Restart nginx # (1)!
  type: button # (2)!
  icon: "🔄" # (3)!
  function: command # (4)!
  command: "systemctl restart nginx" # (5)!
  confirm: true # (6)!

Der Text auf der Taste in Telegram. Er muss unter den benachbarten Einträgen desselben Menüs eindeutig sein.
Hier steht immer button. Verwenden Sie category, wenn Sie ein Untermenü wünschen.
Optionales Emoji vor dem Namen. Es dient nur der Darstellung und ändert nicht, was ausgeführt wird.
Die zu verwendende Funktion. command ist die integrierte Funktion zum Ausführen eines Shell-Befehls.
Was die Funktion command ausführt. Hier funktioniert alles, was Sie in ein Terminal eingeben könnten.
Optional. Vor der Ausführung wird „Are you sure?“ gefragt. Lassen Sie dies bei reinen Leseaktionen weg.

Was beim Antippen geschieht¶

Der Bot sendet eine kurze Zeile Running, damit Sie wissen, dass die Ausführung begonnen hat.
Der Befehl wird auf dem Rechner ausgeführt, auf dem der Bot läuft.
Die Ausgabe kommt als Codeblock mit Exit-Code und Ausführungsdauer zurück. Kurze Ausgaben bleiben als eine oder mehrere Nachrichten im Chat; längere Ausgaben können als .txt-Datei ankommen (siehe Lange Ergebnisse als Datei).
Sie bleiben im aktuellen Menü, sodass Back diese Kategorie weiterhin verlässt.

Häufige Schaltflächen¶

Etwas prüfenEinen Dienst verwaltenEin Protokoll lesenEin Skript ausführenEine destruktive Aktion

Laufzeit-Schaltfläche

- name: Uptime
  type: button
  function: command
  command: "uptime"

Schaltfläche zum Neustarten von nginx

- name: Restart nginx
  type: button
  icon: "🔄"
  function: command
  command: "systemctl restart nginx"

Schaltfläche für das nginx-Protokoll

- name: Nginx log
  type: button
  function: command
  command: "journalctl -u nginx -n 50 --no-pager"

Schaltfläche für die nächtliche Sicherung

- name: Nightly backup
  type: button
  function: script
  path: "/usr/local/bin/backup.sh"

Schaltfläche zum Stoppen von nginx

- name: Stop nginx
  type: button
  icon: "🛑"
  function: command
  command: "systemctl stop nginx"
  confirm: true

Symbole¶

icon setzt ein Emoji vor den Namen. Es ist rein dekorativ und kann jederzeit geändert oder entfernt werden, ohne den ausgeführten Befehl zu verändern.

Ein Symbol ändert nur die Beschriftung

Dieselbe Schaltfläche mit und ohne Symbol

- name: Disk usage
  type: button
  function: command
  command: "df -h"

- name: Disk usage
  type: button
  icon: "💾"
  function: command
  command: "df -h"

Vor riskanten Aktionen nachfragen¶

Fügen Sie confirm: true hinzu. Der Bot fragt dann zunächst mit Yes oder Cancel nach. Verwenden Sie dies für alles, was einen Dienst stoppt, Daten löscht oder den Rechner neu startet. Die Aufforderung läuft nach einer Weile ab (standardmäßig nach fünf Minuten).

Unter Bestätigung erfahren Sie, wann eine Rückfrage sinnvoll ist und wie Sie die Wartezeit ändern.

Einstellungen nur für eine Schaltfläche¶

Die meisten globalen Einstellungen lassen sich für eine einzelne Schaltfläche überschreiben. Das ist praktisch, wenn sich ein Auftrag anders verhält:

Einstellungen für einen langsamen Auftrag überschreiben

Ein langsamer Auftrag in einem anderen Verzeichnis

- name: Long backup
  type: button
  function: command
  command: "/usr/local/bin/backup.sh"
  timeout: "10m"
  workdir: "/var/backups"
  env:
    BACKUP_MODE: "full"

timeout gibt diesem Befehl mehr Zeit, workdir wählt sein Arbeitsverzeichnis und env ergänzt Umgebungsvariablen nur für ihn.

Lange Ergebnisse als Datei¶

output brauchen Sie an einem Button nicht. Lassen Sie es weg, gilt die Root-Einstellung (auto, sofern Sie sie nicht geändert haben): ein kurzes Ergebnis bleibt als Chatnachrichten, und ein Ergebnis, das mehr als zwei Nachrichten bräuchte, kommt als eine .txt-Datei. Setzen Sie output nur, wenn genau dieser Button immer eine Datei oder immer Text senden soll. max_output_messages gibt es an einem Button nicht.

Setzen Sie output: file an einem Button, der oft viel ausgibt (zum Beispiel Logs), oder output: text, um das alte Split-Verhalten nur für diesen Button zu behalten.

Die Root-Schlüssel output und max_output_messages sind unter Konfiguration → Umfang der angezeigten Befehlsausgabe beschrieben. Ausgabe steuern geht jede Kombination aus Root und Button mit je einem Beispiel durch.

Werte für die Funktion¶

Schreiben Sie Funktionswerte direkt auf die Schaltfläche. command, path und args sind Kurzfelder für gleichnamige Parameter. Eigene Namen wie url, host, unit und lines funktionieren genauso.

Eigene Werte übergeben

Aktuelle nginx-Protokolle

- name: Nginx logs
  type: button
  function: journal-unit
  unit: "nginx.service"
  lines: 100

Verschachteln Sie diese Werte nicht unter params:. Jeder Schlüssel muss einem von der ausgewählten Funktion deklarierten Parameter entsprechen. validate meldet unbekannte Namen, fehlende erforderliche Werte sowie ungültige int- oder bool-Werte.

Konfiguration¶

Alle von einer Schaltfläche akzeptierten Felder finden Sie unter Konfiguration → Menü.