Was ist eine Funktion?¶

Eine Funktion ist ein Rezept, das benannte Werte (ihre Parameter) in einen Shell-Befehl umwandelt. Jede Schaltfläche in Ihrem Menü nennt in ihrem Feld function genau eine Funktion.

Stellen Sie sich eine Funktion als Lückentext für einen Befehl vor. Eine Funktion zur Anzeige der Datenträgerbelegung besitzt eine Lücke — den Pfad — die Sie auf jeder Schaltfläche ausfüllen.

Was beim Antippen einer Schaltfläche geschieht¶

Der Bot sucht die Funktion, die im Feld function der Schaltfläche genannt ist.
Er sammelt die auf dieser Schaltfläche angegebenen Werte.
Er erstellt aus diesen Werten einen Shell-Befehl.
Er führt den Befehl in der Shell aus und sendet die Ausgabe als Codeblock an den Chat zurück.

Wenn die Funktion nicht existiert oder ein benötigter Wert fehlt, startet der Bot gar nicht erst: validate meldet das Problem zuvor.

Ein vollständiges Beispiel¶

Die Funktion command ist integriert und immer verfügbar. Sie führt den Inhalt des Felds command einer Schaltfläche aus.

Die integrierte Funktion command verwenden

Laufzeit-Schaltfläche

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

Tippen Sie Laufzeit an. Der Bot führt uptime auf dem Server aus und sendet die Ausgabe zurück.

Werte von einer Schaltfläche übergeben¶

Schreiben Sie jeden Wert direkt auf die Schaltfläche. Dafür gibt es zwei Möglichkeiten:

Verwenden Sie die Kurzfelder command, path und args. Jedes davon füllt den gleichnamigen Parameter.
Verwenden Sie für jeden anderen Parameter dessen Namen als Schlüssel auf der Schaltfläche.

Eine URL über ihren Parameternamen übergeben

Schaltfläche zum Prüfen der API

- name: API prüfen
  type: button
  function: curl-url
  url: "https://example.com/health"

Hier entspricht url dem von curl-url deklarierten Parameter url. Dieselbe Regel gilt für Namen wie host, unit und lines.

Werte nicht in params: verschachteln

params: gehört in eine eigene Funktionsdatei und deklariert dort die von der Funktion akzeptierten Werte. Schreiben Sie auf einer Schaltfläche jeden Wert direkt:

Werte gehören direkt auf die Schaltfläche

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

Numerische YAML-Werte benötigen keine Anführungszeichen.

validate prüft jeden Schlüssel gegen die Parameter der ausgewählten Funktion. Ein Tippfehler oder nicht deklarierter Name lässt die Validierung fehlschlagen. Auch als int oder bool deklarierte Werte werden geprüft. Für ausgelassene optionale Werte werden die Standardwerte verwendet.

Zwei Arten von Funktionen¶

Funktionen sind entweder im Programm enthalten oder stammen aus einer YAML-Datei auf Ihrem Server. Sobald eine Schaltfläche sie verwendet, verhalten sich beide Arten gleich.

	Integriert	Eigen
Herkunft	Im Programm enthalten	Eine von Ihnen geschriebene YAML-Datei
Müssen Sie eine Datei erstellen?	Nein	Ja, eine Datei pro Funktion
Namen	Reserviert (`command`, `script`)	Jeder nicht reservierte Name
Immer verfügbar?	Ja	Nur, wenn Sie `function_directory` festlegen
Bearbeitbar?	Nein	Ja, es sind Ihre Dateien

Sie können beide Arten im selben Menü frei kombinieren. Die meisten Menüs beginnen ausschließlich mit command-Schaltflächen. Wechseln Sie zu eigenen Funktionen, wenn Sie denselben Befehl mit kleinen Abweichungen wiederholen.

Integrierte Funktionen¶

Zwei Funktionen werden immer geladen, auch wenn Sie kein function_directory festlegen. Ihre Felder command, path und args stehen direkt auf einer Schaltfläche.

Funktion	Aufgabe	Erforderlich	Optional
`command`	Führt einen Shell-Befehl unverändert aus	`command`	—
`script`	Führt eine Skriptdatei mit Argumenten aus	`path`	`args`

Beide Namen sind reserviert. Eine eigene Funktionsdatei darf sie nicht wiederverwenden. Der Loader stoppt mit einem Fehler wie function name "command" is reserved, und der Bot startet nicht.

Eigene Funktionen¶

Eine eigene Funktion ist eine einzelne YAML-Datei, die einen wiederverwendbaren Befehl beschreibt. Bewahren Sie diese Dateien in einem eigenen Ordner auf und lassen Sie function_directory darauf verweisen.

Dem Bot den Speicherort Ihrer Funktionsdateien mitteilen

config.yaml

function_directory: "./functions"

Der Bot liest diesen Ordner einschließlich seiner Unterordner beim Start und lädt jede .yaml- und .yml-Datei. Andere Dateien werden ignoriert.

Das Release-Archiv enthält bereits einen Ordner functions/ mit fünf Beispielen, die Sie unverändert verwenden können:

Funktion	Aufgabe	Schaltflächenwerte
Echo Script	Führt ein Skript über Bash aus	`path`, optional `args`
Disk path	Zeigt die Datenträgerbelegung	optional `path`
Curl URL	Ruft eine URL ab	`url`
Ping Host	Pingt einen Host	`host`, optional `count`
Journal Unit	Zeigt aktuelle Dienstprotokolle	`unit`, optional `lines`

Beginnen Sie zum Schreiben einer eigenen Funktion mit der Dateistruktur oder folgen Sie der Schritt-für-Schritt-Anleitung.

Geladene Funktionen prüfen

Alle für den Bot sichtbaren Funktionen auflisten

./telegram-commander list-functions --config config.yaml

Integrierte Funktionen zeigen source=builtin; eigene Funktionen zeigen die Datei, aus der sie stammen.

Sicherheitshinweise¶

Schaltflächen werden mit den Rechten des Bots ausgeführt

Befehle werden mit den Rechten des Kontos ausgeführt, unter dem der Bot läuft. Ist dies root (wie bei der standardmäßigen Dienst-Einrichtung), können Schaltflächen alles auf dem Host ausführen. Fügen Sie nur zugelassene Benutzer hinzu, denen Sie vertrauen.

Parameterwerte werden als Text in den Befehl eingesetzt. Behandeln Sie sie wie Shell-Eingaben: Verwenden Sie vorzugsweise feste Schaltflächenwerte und ergänzen Sie confirm: true für alle destruktiven Aktionen.

Lange Ausgaben werden gekürzt und aufgeteilt

Befehle enden nach ihrem timeout, und der Bot behält höchstens max_output_bytes ihrer Ausgabe. Alles, was länger als eine Telegram-Nachricht ist, wird als mehrere Nachrichten gesendet. Siehe Konfiguration → Umfang der angezeigten Befehlsausgabe.