Modul

Chute unterstützt externe Moduldateien (.sgmodule), um die Konfiguration mit wiederverwendbaren, gemeinsam nutzbaren Regeln, Skripten, MitM-Hosts und DNS-Zuordnungen zu erweitern. Module folgen dem Surge-Modulformat.

Module werden im Abschnitt [Module] definiert:

[Module]
https://example.com/my-module.sgmodule
/Users/me/.chute/custom-module.sgmodule
~/.chute/another-module.sgmodule

http://- und https://-Module werden remote abgerufen; eine lokale Datei wird als bloßer Pfad geschrieben — /path/to/local-module.sgmodule oder ~/.chute/local-module.sgmodule —, und in dieser Form wird sie auch beim Speichern der Konfiguration zurückgeschrieben. Eine file:///-URL funktioniert ebenfalls. Eine lokale Moduldatei, die sich nicht lesen lässt, wird mit einer Warnung im Protokoll übersprungen.

Moduldateistruktur

Eine .sgmodule-Datei folgt derselben Syntax wie die Hauptkonfigurationsdatei. Unterstützte Abschnitte:

Aus Kompatibilitätsgründen wird ein [DNS]-Abschnitt in einem Modul als Alias für [Host] akzeptiert.

Modulmetadaten

Module können Metadaten-Direktiven enthalten (Zeilen, die mit #! beginnen):

#!name = My Custom Module
#!desc = Blocks ads and trackers for example.com
#!system = ios,macos

#!system sind informative Metadaten, die im Moduleditor angezeigt werden; sie steuern das Laden derzeit nicht — das Modul wird auf allen Plattformen angewendet.

#!arguments darf mehrfach vorkommen; spätere Deklarationen überschreiben frühere. {{{variable}}}-Platzhalter im Modulinhalt werden durch den Standardwert ersetzt, den #!arguments für die Variable deklariert, oder durch die leere Zeichenkette, wenn keiner deklariert ist. Derzeit bietet keine App eine Möglichkeit, die Argumente eines Moduls zu überschreiben; es gelten also immer die deklarierten Standardwerte.

Eine Zeile mit dem Präfix #!IOS-ONLY, #!MACOS-ONLY oder #!TVOS-ONLY gilt nur auf dieser Plattform und entfällt anderswo — egal wo sie steht, im Modul wie in der Konfigurationsdatei selbst:

[Rule]
#!IOS-ONLY DOMAIN-SUFFIX,mobile-ads.example,REJECT
#!MACOS-ONLY PROCESS-NAME,Updater,REJECT

Beim Speichern der Konfiguration durch die App bleibt das Präfix wie geschrieben erhalten: Eine auf dieser Plattform ausgeschlossene Zeile wird weder aus der Datei entfernt noch zu einem Kommentar, sodass dasselbe Profil auf den anderen Plattformen weiter funktioniert.

Modulbeispiel

#!name = Ad Block Module
#!desc = Block common ad domains
#!system = ios,macos

[Rule]
DOMAIN-SUFFIX,doubleclick.net,REJECT
DOMAIN-SUFFIX,googlesyndication.com,REJECT
DOMAIN-SUFFIX,googleadservices.com,REJECT

[Host]
localhost = 127.0.0.1

[MITM]
hostname = *.google-analytics.com

[URL Rewrite]
^https://example\.com/old-api https://example.com/new-api 302

%APPEND%- / %INSERT%-Direktiven innerhalb des hostname-Werts eines Moduls werden entfernt und die Hostnamen mit der MitM-Liste zusammengeführt; ein vorangestelltes - als Ausschluss-Präfix an einem Hostnamen bleibt erhalten.

Der Abschnitt [General] eines Moduls kann fünf Listenoptionen der laufenden Konfiguration erweitern — skip-proxy, tun-excluded-routes, tun-included-routes, dns-server und always-real-ip — mit %APPEND% (hinten anfügen) oder %INSERT% (vorne einfügen). Zusammengeführt wird bei allen fünf; welche Plattformen die beiden Routenlisten in ihren Tunneln lesen, steht unter Eingeschlossene Routen und Ausgeschlossene Routen. Die Werte werden beim Anwenden des Moduls zusammengeführt und beim Entfernen oder Deaktivieren wieder zurückgenommen. Ein Wert ohne Direktive wird mit einem Hinweis ebenfalls angehängt, da das Ersetzen der ganzen Liste nicht unterstützt wird; jeder andere [General]-Schlüssel wird mit einem Hinweis ignoriert.

[General]
skip-proxy = %APPEND% *.corp.example, 10.20.0.0/16

Modullebenszyklus

• Module werden geladen, nachdem die Hauptkonfiguration geparst wurde.
• Regeln, Skripte, MitM-Hosts und DNS-Hosts aus Modulen werden zu den Laufzeit-Managern hinzugefügt.
• [Rule]-Zeilen aus Modulen laufen nach den automatischen Tailscale-Regeln und vor den eigenen Regeln der Konfiguration, in Ladereihenfolge der Module — wie bei Surge, sodass das REJECT eines Werbeblocker-Moduls nicht von einer früheren Regel im Profil verdeckt wird.
• [Map Local], [Body Rewrite] und [General]-Zusammenführungen aus Modulen werden nach einem Neuladen der Konfiguration erneut angewendet.
• Wenn ein Modul entfernt oder deaktiviert wird, werden alle seine Regeln, Skripte und Hosts abgemeldet.
• Remote-Modulinhalte werden beim Start des Tunnels abgerufen und nur dann erneut abgerufen, wenn sich die [Module]-URL-Liste bei einem Neuladen der Konfiguration ändert.