Module

Chute prend en charge des fichiers de module externes (.sgmodule) permettant d'étendre la configuration avec des règles, des scripts, des hôtes MitM et des mappages DNS réutilisables et partageables. Les modules suivent le format de module Surge.

Les modules sont déclarés dans la section [Module] :

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

Les modules en http:// et https:// sont récupérés à distance ; un fichier local s'écrit comme un simple chemin — /path/to/local-module.sgmodule ou ~/.chute/local-module.sgmodule —, forme sous laquelle la configuration est d'ailleurs réenregistrée. Une URL file:/// fonctionne aussi. Un fichier de module local illisible est ignoré, avec un avertissement dans le journal.

Structure d'un fichier de module

Un fichier .sgmodule suit la même syntaxe que le fichier de configuration principal. Sections prises en charge :

Pour des raisons de compatibilité, une section [DNS] dans un module est acceptée comme alias de [Host].

Métadonnées de module

Les modules peuvent inclure des directives de métadonnées (lignes commençant par #!) :

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

#!system est une métadonnée informative affichée dans l'éditeur de modules ; elle ne conditionne pas actuellement le chargement — le module est appliqué sur toutes les plateformes.

#!arguments peut apparaître plusieurs fois ; les déclarations les plus récentes remplacent les précédentes. Les espaces réservés {{{variable}}} présents dans le corps du module sont remplacés par la valeur par défaut que #!arguments déclare pour la variable, ou par la chaîne vide si elle n'en déclare aucune. Aucune application ne permet pour l'instant de remplacer les arguments d'un module : ce sont donc toujours les valeurs par défaut déclarées qui s'appliquent.

Une ligne préfixée par #!IOS-ONLY, #!MACOS-ONLY ou #!TVOS-ONLY ne s'applique que sur cette plateforme et est ignorée ailleurs — où qu'elle figure, dans un module comme dans le fichier de configuration lui-même :

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

Lorsque l'application enregistre la configuration, le préfixe est conservé tel qu'écrit : une ligne exclue sur cette plateforme n'est ni retirée du fichier ni transformée en commentaire, si bien que le même profil continue de fonctionner sur les autres plateformes.

Exemple de module

#!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

Les directives %APPEND% / %INSERT% présentes dans la valeur hostname d'un module sont supprimées et les noms d'hôte fusionnés dans la liste MitM ; un préfixe d'exclusion - en tête d'un nom d'hôte est conservé.

La section [General] d'un module peut étendre cinq options de type liste de la configuration en cours — skip-proxy, tun-excluded-routes, tun-included-routes, dns-server et always-real-ip — avec %APPEND% (ajout à la fin) ou %INSERT% (ajout au début). La fusion a bien lieu pour les cinq ; les tunnels qui lisent les deux listes de routes, selon la plateforme, sont décrits sous Routes incluses et Routes exclues. Les valeurs sont fusionnées quand le module est appliqué et retirées quand il est supprimé ou désactivé. Une valeur sans directive est elle aussi ajoutée à la fin, avec un avis, car le remplacement de la liste entière n'est pas pris en charge ; toute autre clé de [General] est ignorée avec un avis.

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

Cycle de vie d'un module

• Les modules sont chargés après l'analyse de la configuration principale.
• Les règles, scripts, hôtes MitM et hôtes DNS issus des modules sont ajoutés aux gestionnaires d'exécution.
• Les lignes [Rule] des modules passent après les règles Tailscale automatiques et avant les règles propres de la configuration, dans l'ordre de chargement des modules — comme dans Surge, de sorte que le REJECT d'un module anti-publicité n'est pas masqué par une règle antérieure du profil.
• Les fusions [Map Local], [Body Rewrite] et [General] venant des modules sont réappliquées après un rechargement de la configuration.
• Lorsqu'un module est supprimé ou désactivé, toutes ses règles, ses scripts et ses hôtes sont désenregistrés.
• Le contenu des modules distants est récupéré au démarrage du tunnel, et retéléchargé uniquement lorsque la liste d'URL [Module] change lors d'un rechargement de configuration.