Options diverses

[General]
ipv6 = true
loglevel = notify

skip-proxy = 127.0.0.1, 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12, 100.64.0.0/10, localhost, *.local

tun-excluded-routes = 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12
tun-included-routes = 192.168.1.12/32

Options courantes

Activer la prise en charge complète d'IPv6 (par défaut : true)

ipv6 = true

loglevel (par défaut : warning)

loglevel = notify

L'une des valeurs none, fatal, warning, notify, info ou verbose. Il n'est pas recommandé d'activer verbose au quotidien, car cela dégrade nettement les performances.

skip-proxy

skip-proxy = 127.0.0.1, 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12, 100.64.0.0/10, localhost, *.local

Sur les versions iOS et tvOS, une entrée de type nom d'hôte est ajoutée à la liste d'exceptions du proxy du tunnel, si bien que les connexions vers cet hôte sont traitées par le TUN de Chute plutôt que par le proxy de Chute ; une entrée de type adresse IP ou CIDR devient en outre une route exclue du tunnel, si bien que le trafic vers cette plage quitte entièrement le tunnel au lieu d'être traité par le TUN de Chute. Chute Android fait de même en mode VPN : tant que Proxy HTTP système est activé, les noms d'hôte, les jokers * et les adresses IPv4 rejoignent la liste d'exceptions du proxy que le VPN transmet aux applications, et à partir d'Android 13 chaque entrée d'adresse IP ou de CIDR devient une route exclue du VPN — une adresse seule comme route /32 ou /128 ; les entrées de bouclage (loopback) sont laissées de côté, puisque le trafic de bouclage n'entre jamais dans le tunnel. Sur la version macOS, ces réglages sont appliqués au système lorsque « Définir comme proxy système » est activé. Cette option sert à corriger des problèmes de compatibilité avec certaines apps.

• Pour indiquer un seul domaine, saisissez le nom de domaine — par exemple, apple.com.
• Pour indiquer tous les sites d'un domaine, placez un astérisque devant le nom de domaine — par exemple, *apple.com.
• Pour indiquer une partie précise d'un domaine, précisez chaque partie — par exemple, store.apple.com.
• Pour indiquer des hôtes ou des réseaux par adresse IP, saisissez une adresse IP précise telle que 192.168.2.11 ou une plage d'adresses, telle que 192.168.2.* ou 192.168.2.0/24.

Remarque : si vous saisissez une adresse IP ou une plage d'adresses, vous ne pourrez contourner le proxy que lorsque vous vous connecterez à cet hôte par cette adresse, et non lorsque vous vous y connecterez par un nom de domaine qui résout vers cette adresse.

Écoute du serveur proxy

interface = 127.0.0.1
port = 8118
socks-interface = 127.0.0.1
socks-port = 8119

interface / port contrôlent l'adresse et le port d'écoute du serveur proxy HTTP (par défaut 127.0.0.1:8118). socks-interface / socks-port contrôlent le serveur proxy SOCKS5 (par défaut 127.0.0.1:8119).

Pour une requête http:// en clair, le serveur proxy HTTP ne porte qu'un échange par connexion : chaque réponse part avec Connection: close et la connexion se ferme ensuite, si bien que le client envoie sa requête suivante sur une nouvelle connexion. Une requête envoyée en pipeline derrière la première est abandonnée, et le client la renvoie sur la nouvelle connexion. Un schéma d'authentification qui a besoin de plusieurs allers-retours sur la même connexion, comme NTLM ou Negotiate, ne peut pas aboutir à travers lui. Un tunnel CONNECT non déchiffré n'est pas concerné. Une mise à niveau WebSocket conserve sa connexion : après la réponse 101, les données passent telles quelles dans les deux sens.

Alias de compatibilité : doh-server et doh-service sont acceptés comme alias de doh ; http-listen / socks5-listen (par ex. 0.0.0.0:6152, [::]:6153, ou un simple port) sont associés aux réglages d'interface/port ci-dessus. Un hôte d'écoute joker (0.0.0.0, :: ou *) définit également allow-wifi-access = true.

Authentification du proxy entrant

http-auth = username:password

Exige des clients qu'ils s'authentifient avant d'utiliser les serveurs proxy HTTP et SOCKS5 de Chute. La ligne peut être répétée pour autoriser plusieurs jeux d'identifiants.

Le proxy HTTP répond à une requête sans identifiants valides — requête ordinaire comme CONNECT — par 407 Proxy Authentication Required avec Proxy-Authenticate: Basic realm="KLNEKit", puis ferme la connexion. Le serveur SOCKS5 reçoit les mêmes identifiants par l'authentification nom d'utilisateur/mot de passe de SOCKS5 et ferme une connexion qui ne la propose pas ou qui y échoue.

Contourner les requêtes système

bypass-system = true

Lorsque cette option est activée, Chute ajoute à skip-proxy une liste fixe de 18 noms d'hôte Apple — push, passerelle iCloud, vérification de portail captif, OCSP et autres — et ajoute IP-CIDR,17.0.0.0/8,DIRECT,no-resolve après vos règles, juste avant FINAL — une règle à vous qui correspond d'abord à 17.0.0.0/8 l'emporte donc toujours. Il n'y a aucune correspondance par processus : l'option est cette liste fixe d'hôtes et d'adresses, pas un filtre sur le processus à l'origine de la requête.

Par défaut : true.

Toujours IP réelle

always-real-ip = *.example.com, tracker.example.org

Lorsque Chute fournit de fausses adresses IP pour les requêtes DNS détournées (voir hijack-dns), les noms d'hôte correspondant à cette liste séparée par des virgules reçoivent toujours en réponse leurs véritables adresses IP résolues. Les jokers sont pris en charge. always-ip-address (graphie de Shadowrocket) est lu comme cette clé : une valeur booléenne (true, yes, on, 1) signifie tous les hôtes et est réécrite en always-real-ip = * ; false est abandonné ; toute autre valeur est lue comme une liste d'hôtes. La configuration est enregistrée avec la graphie always-real-ip.

Lire le fichier hosts du système

read-etc-hosts = false

Indique si le fichier hosts du système est lu dans la table [Host]. Mettez false pour ignorer ce fichier ; une modification prend effet au rechargement. Voir Mappage DNS local.

Par défaut : true.

Interrompre les connexions existantes

interrupt-exist-connections = true

Lorsque cette option est activée, changer la politique sélectionnée dans un groupe de politiques (via URL Test, Fallback, Load Balance, SSID ou sélection manuelle) ferme proprement les connexions existantes qui utilisaient l'ancienne politique. Cela garantit que les connexions utilisent immédiatement le proxy nouvellement sélectionné plutôt que de s'attarder sur l'ancien.

Cela vaut pour chaque groupe de politiques que traverse une connexion : le groupe nommé par sa règle, un groupe imbriqué dans celui-ci, le groupe amont d'une politique chaînée (underlying-proxy) et les groupes membres d'un groupe de relais.

Chaque connexion concernée est fermée proprement avec un délai de 3 secondes avant une fermeture forcée.

Par défaut : false. Il s'agit d'un réglage global — il affecte tous les groupes de politiques.

Network Framework (macOS / iOS / tvOS)

network-framework = true

Active Network.framework d'Apple pour les connexions sortantes. Network.framework peut offrir de meilleures performances et une intégration moderne de la pile TLS sur les plateformes prises en charge.

Par défaut : true sur macOS, false sur iOS et tvOS.

Exclure les noms d'hôte simples

exclude-simple-hostnames = true

Lorsque cette option est activée, les requêtes vers des noms d'hôte simples (noms à étiquette unique sans point, par ex. localhost) contournent les règles de proxy et sont résolues localement. Cela évite des résolutions DNS inutiles pour les noms du réseau local. Il s'agit du réglage « Exclure les noms d'hôte simples » du proxy système de macOS lui-même : Chute Mac l'écrit dans la configuration du proxy système, il ne s'applique donc qu'aux applications qui suivent le proxy système — ni au mode amélioré ni au trafic TUN. Sous iOS et tvOS, il est écrit de la même façon dans les réglages de proxy du tunnel : un nom d'hôte simple est alors traité par le TUN de Chute plutôt que par le proxy de Chute, comme un nom d'hôte de skip-proxy. Chute Android ne l'utilise pas.

Sur Chute Mac, une migration ponctuelle active cette option par défaut au premier lancement ; un réglage explicitement désactivé par l'utilisateur est respecté.

Par défaut : false.

Désactiver l'enregistrement en base de données

disable-db-record = true

Lorsque cette option est activée, Chute cesse d'écrire les enregistrements de trafic dans la base de données locale. Cela peut améliorer les performances et réduire l'usage du stockage, mais l'historique de trafic ne sera pas disponible dans Chute Dashboard.

Par défaut : false.

Affichage de la vitesse dans la barre des menus (Mac uniquement)

menu-bar-show-speed = true

Lorsque cette option est activée, Chute Mac affiche les vitesses d'envoi et de réception actuelles dans la barre des menus.

Analysée mais sans effet dans le moteur actuel — rien dans Chute Mac ne lit cette clé. La vitesse dans la barre des menus se bascule depuis l'entrée de menu Afficher la vitesse de connexion, stockée dans les réglages propres à l'app. La clé est tout de même réécrite à l'enregistrement de la configuration.

Détourner les autres serveurs DNS

hijack-dns = 8.8.8.8:53

Par défaut, Chute ne renvoie de fausses adresses IP que pour les requêtes DNS envoyées à l'adresse DNS de Chute (198.18.0.2). Les requêtes envoyées à un DNS standard sont simplement transmises.

Certains appareils ou logiciels utilisent toujours un serveur DNS codé en dur. (Par exemple, les enceintes Google utilisent toujours 8.8.8.8). Vous pouvez utiliser cette option pour détourner la requête et obtenir une fausse adresse.

Vous pouvez utiliser hijack-dns = *:53 pour détourner toutes les requêtes DNS.

Une entrée sans port signifie le port 53 : hijack-dns = 8.8.8.8 équivaut à 8.8.8.8:53. Une entrée illisible est ignorée avec un avis ; le reste de la ligne s'applique toujours.

La fausse IP est aussi disponible sur Apple TV (tvOS 17 et ultérieur). Elle y était désactivée ; la vérification sur un appareil est encore en cours.

Routes exclues

tun-excluded-routes = 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12

Chute VIF ne peut traiter que les protocoles TCP et UDP. Utilisez cette option pour contourner des plages d'IP précises afin de laisser passer tout le trafic.

Remarque : cette option s'applique aux tunnels de paquets iOS et tvOS, où les plages deviennent des routes exclues des réglages IP du tunnel, ainsi qu'à Chute Android sous Android 13 et ultérieur, où elles deviennent des routes exclues du VPN — Android 11 et 12 n'offrent pas d'API pour les routes exclues, les plages y sont donc ignorées. Elle n'a aucun effet sous macOS, quel que soit le type de mode amélioré — ni l'utun de l'assistant, ni l'extension réseau Mac n'excluent la moindre route. Les requêtes traitées par le serveur proxy de Chute ne sont pas concernées. Combinez « skip-proxy » et « tun-excluded-routes » pour vous assurer que certains flux HTTP contournent bien Chute.

Cette option peut provoquer une erreur système ENOMEM (Cannot allocate memory). Il semble s'agir d'un bug du système iOS. Évitez si possible d'utiliser cette option.

Routes incluses

tun-included-routes = 192.168.1.12/32

Par défaut, l'interface Chute VIF se déclare comme route par défaut. Mais comme l'interface Wi-Fi possède une route plus spécifique, une partie du trafic peut ne pas passer par l'interface Chute VIF. Utilisez cette option pour ajouter une route plus spécifique.

Pourquoi une route par défaut ne suffit pas : le système choisit une route d'après la longueur du préfixe, et non d'après l'ordre. Le sous-réseau directement connecté de l'interface physique elle-même — 192.168.1.0/24, par exemple — est plus spécifique que le 0.0.0.0/0 du tunnel, si bien que ce trafic n'atteint jamais Chute. Une entrée ajoutée ici installe une route encore plus spécifique et l'emporte. Ces routes s'ajoutent à la route par défaut et ne restreignent jamais ce que le tunnel capture.

Remarque : évitez d'énumérer en bloc les plages privées (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16). C'est normalement inutile et cela peut perturber le routage propre au système ; Chute respecte une telle entrée mais consigne un avertissement — sauf sous la variante Network Extension du mode amélioré sur macOS, qui la respecte sans avertissement. La raison habituelle de recourir à cette option est de joindre une plage que possède le tunnel d'une autre application VPN.

Remarque : une entrée qui scierait la branche sur laquelle Chute est assis est refusée, motif à l'appui dans le journal : la boucle locale, les sous-réseaux propres au VIF (198.18.0.0/15 et fd12:1:1:1::/64), le link-local, le multicast, le broadcast et une longueur de préfixe de 0. La variante Helper utun du mode amélioré sur macOS refuse en outre une entrée qui couvre la passerelle par défaut actuelle. Sous la variante Network Extension, le motif va dans le journal système plutôt que dans celui de Chute.

Remarque : sur iPhone, le système décide séparément de la capture du réseau local. Un sous-réseau local listé ici n'est honoré que si Inclure les réseaux locaux est également activé dans les réglages de l'application — un interrupteur qu'on ne peut activer que lorsque Inclure tous les réseaux est activé ; une plage que possède le tunnel d'une autre application n'a besoin d'aucun interrupteur de ce genre. Chute tvOS affiche les mêmes interrupteurs mais ne les applique pas au tunnel. Sous macOS, les routes sont installées directement et aucune condition de ce type ne s'applique.

Remarque : sous macOS, la variante Helper utun du mode amélioré installe ces routes au moment où l'interface est attachée, si bien qu'une liste modifiée rattache l'interface au rechargement. Cette option exige la version 0.8.6 ou ultérieure de l'assistant — après une mise à jour de Chute, approuvez une fois l'invite de réinstallation de l'assistant, faute de quoi la variante Helper utun signale que l'assistant n'est pas en cours d'exécution.

Détection de protocole

sniffing-enabled = true
sniffing-timeout = 100

Chute peut détecter le protocole réel d'une connexion en inspectant les premiers octets. Cela permet à des règles comme PROTOCOL,TLS,Proxy de fonctionner correctement même pour des connexions entrantes non HTTP.

sniffing-enabled (par défaut : false)

sniffing-enabled = true

Active la détection de protocole pour les connexions TCP. En mode amélioré, le même interrupteur permet de traiter par nom un flux HTTP/3 (QUIC) vers une adresse IP nue : Chute lit le nom du serveur dans le ClientHello QUIC, les règles de type DOMAIN voient ce nom plutôt que l'adresse, et chaque paquet suivant du flux suit le verdict du premier. Un ClientHello trop grand pour un seul paquet — courant avec l'échange de clés post-quantique — est réassemblé par flux à partir des paquets Initial qui le transportent, dans la limite d'un hello réassemblé de 16 Kio, de sorte que son nom est lu lui aussi. Tant que le reste du hello n'est pas arrivé, les datagrammes du flux sont retenus au lieu d'être envoyés avec leur adresse nue, et repartent ensemble selon la politique du nom une fois celui-ci lu — le premier fragment d'un hello découpé ne prend donc plus une route différente du reste. Les garde-fous sont une attente d'une seconde, huit datagrammes ou 16 Kio retenus par flux, et 64 flux en cours de réassemblage à la fois ; un flux au-delà de l'un d'eux, ou dont les paquets Initial ne complètent jamais le ClientHello, est traité par adresse comme auparavant.

Pour une connexion vers une adresse réelle, les règles voient le nom que le client annonce lui-même — le SNI TLS ou l'en-tête HTTP Host —, même si le cache DNS de Chute connaît déjà un nom pour cette adresse : le cache ne garde qu'un nom par adresse, le dernier à s'y être résolu, et derrière une adresse partagée ce peut être celui d'un autre site. Le nom du cache est utilisé lorsque rien ne peut être lu dans la connexion. Une requête écrite pour un proxy HTTP — CONNECT, ou une requête dont la cible est une URL complète — reste détectée comme HTTP, mais l'hôte qu'elle nomme est la prochaine destination de ce proxy, pas le nom de cette connexion ; la connexion garde le nom du cache ou l'adresse. Un protocole où le serveur parle le premier ne donne aucun nom à lire : les connexions vers les ports 21, 22, 23, 25, 110, 119, 143, 587, 2525 et 3306 ne passent pas par la détection et sont établies immédiatement ; sur tout autre port, un tel protocole attend l'expiration de sniffing-timeout avant d'être connecté.

sniffing-timeout (par défaut : 100 ms)

sniffing-timeout = 200

Temps maximal, en millisecondes, d'attente des données initiales pour déterminer le protocole. Augmentez cette valeur si la détection de protocole échoue sur des connexions lentes.

Bloquer QUIC

block-quic = auto

Contrôle si Chute rejette le trafic QUIC détecté, y compris HTTP/3. QUIC fonctionne sur UDP et ne peut pas être déchiffré par le MitM HTTP de Chute. Rejeter QUIC peut inciter les clients compatibles à réessayer en TCP, ce qui permet un traitement par proxy sur TCP et, si elle est configurée, l'application du déchiffrement HTTPS.

Pour le trafic entrant par le TUN, Chute répond à un flux QUIC rejeté par un message ICMP/ICMPv6 Port Unreachable, afin que les clients compatibles puissent se rabattre sans attendre l'expiration d'un délai QUIC.

Un flux QUIC rejeté est enregistré avec REJECT comme politique, quelle que soit la politique choisie par la règle.

La détection QUIC pour block-quic est automatique et ne nécessite pas sniffing-enabled ; sniffing-enabled contrôle la détection de protocole — TLS sur TCP, et le nom de serveur d'un flux QUIC. Utilisez une règle PROTOCOL,QUIC,... lorsque vous avez besoin d'un traitement par règles de flux QUIC individuels.

Répondre à l'ICMP dans le tunnel

icmp-auto-reply = false

Une requête d'écho ICMP qui entre dans le tunnel — IPv4 comme IPv6 — reçoit une réponse de Chute lui-même : la réponse est fabriquée localement et rien n'est envoyé à la cible. Toute destination répond donc, y compris une adresse qu'une règle enverrait vers REJECT ou un hôte hors service, si bien qu'un ping qui réussit dans le tunnel ne dit rien de l'accessibilité de la cible. Mettez false pour cesser de répondre : la requête est alors relayée hors de l'appareil, mais sa réponse ne revient jamais par le tunnel, et le ping reste sans réponse.

Par défaut : true. S'applique au trafic arrivant par le TUN ; l'ICMP n'est jamais relayé par un proxy.

Contourner le TUN

bypass-tun = 192.168.0.0/16, 10.0.0.0/8

Similaire à skip-proxy, mais opère au niveau du routage TUN/VIF. Les connexions vers ces plages d'IP contournent entièrement l'interface TUN et passent directement par la pile réseau du système.

Remarque : cette option s'applique aux tunnels de paquets iOS et tvOS, où ses plages rejoignent tun-excluded-routes comme routes exclues du tunnel, et de la même manière à Chute Android sous Android 13 et ultérieur (Android 11 et 12 l'ignorent). Elle n'a aucun effet sous macOS, quel que soit le type de mode amélioré.

Afficher une page d'erreur en cas de rejet

show-error-page-for-reject = true

Lorsque cette option est activée, Chute renvoie une page d'erreur lisible pour les requêtes rejetées. Cela ne vaut que pour une requête arrivée par l'entrée proxy HTTP ; l'option désactivée, une telle requête reçoit HTTP/1.1 503 Service Unavailable à la place. Une requête rejetée venant de toute autre entrée est abandonnée dans les deux cas.

Par défaut : false.

DNS optimiste

optimistic-dns = false

Lorsque cette option est activée, un enregistrement en cache dont le TTL est expiré est tout de même renvoyé immédiatement, pendant qu'il est redemandé en arrière-plan. Cela réduit la latence de connexion, au prix d'un éventuel renvoi d'enregistrements DNS obsolètes. Un enregistrement expiré n'est renvoyé ainsi que pendant un temps limité : une durée égale à son propre TTL, et au moins cinq minutes ; au-delà, la requête attend la réponse de l'amont. Lorsqu'elle est désactivée, un enregistrement dont le TTL est expiré n'est pas servi et la requête part vers l'amont ; cette réponse remplit de nouveau le cache, de sorte que la recherche suivante est servie par le cache. Lors du passage à un autre réseau, ou lorsque la liste des serveurs DNS change, tous les enregistrements en cache sont considérés comme expirés. Elle détermine aussi, sur toutes les plateformes, si le tunnel se connecte à plusieurs adresses d'un même nom à la fois.

Par défaut : true. Définissez optimistic-dns = false pour désactiver.

Autoriser l'accès Wi-Fi

allow-wifi-access = true

Permet aux autres appareils du même réseau d'atteindre les ports proxy HTTP et SOCKS5 de Chute, en élargissant l'adresse d'écoute des deux écouteurs à 0.0.0.0. Les configurations de style Surge — ainsi que la correspondance allow-lan de l'importateur sing-box — ne portent que ce drapeau et laissent interface à sa valeur par défaut 127.0.0.1 ; c'est pourquoi le drapeau doit élargir lui-même l'adresse d'écoute.

Le drapeau et un interface joker explicite sont deux écritures de la même intention, et Chute en prend l'union : une configuration qui écrit déjà 0.0.0.0 se comporte exactement comme avant. Modifier le drapeau relie les deux écouteurs, donc retirer l'accès prend effet au rechargement plutôt qu'au prochain démarrage.

Ce sont les ports du proxy, et ils n'ont aucune authentification tant que http-auth n'est pas défini. Sur un réseau que vous ne contrôlez pas, définissez aussi des identifiants.

Configuration gérée

#!MANAGED-CONFIG https://example.com/config.conf interval=86400 strict=false

Une configuration dont la première ligne est un en-tête #!MANAGED-CONFIG est retéléchargée automatiquement depuis l'URL. Les paramètres de cet en-tête et le comportement de mise à jour sont documentés dans Configuration gérée.

Replica / enregistrement du trafic

replica = true

La clé replica de [General] (replica = true) active l'enregistrement du trafic ; la section [Replica] filtre ce que Chute Dashboard affiche — ses clés sont documentées dans Réplique.

Sur iOS, tvOS et Android, une licence active est en outre nécessaire : sans elle, replica = true ne capture rien.

Accès au contrôleur externe (Chute Dashboard)

external-controller-access = password@0.0.0.0:6155

Démarre le serveur de contrôle distant utilisé par Chute Dashboard. La valeur s'écrit password@host:port ; un nom d'utilisateur peut éventuellement précéder le mot de passe (user:password@host:port). Sur iOS et tvOS, un canal USB complémentaire est ouvert sur port + 1 (pas sur macOS). La connexion est décrite sur la page Chute Dashboard.

API de contrôle HTTP et console web

[General]
external-http-controller = 127.0.0.1:9090
external-http-secret = your-secret-token
external-http-ui = true
external-http-cors = false

Chute fournit une API de contrôle HTTP intégrée et une console web, comparables aux tableaux de bord de Clash et de Surge. L'API expose l'état du moteur, le trafic, les connexions, le DNS, les contrôles de politique et la gestion de configuration via des points de terminaison REST.

La forme Surge http-api = <secret>@<host>:<port> est lue comme external-http-controller plus external-http-secret. Un profil peut aussi écrire les parties séparément : http-api-secret, http-api-ui et http-api-cors sont lues comme external-http-secret, external-http-ui et external-http-cors, et http-api-web-dashboard également comme external-http-ui ; la configuration est enregistrée avec les clés external-http-*. http-api-tls n'est pas pris en charge — le contrôleur parle HTTP en clair — et ne produit qu'un avis.

external-http-controller (par défaut : désactivé)

external-http-controller = 127.0.0.1:9090

Les requêtes que la console garde résidentes pendant le service sont plafonnées à 4 Mo sous macOS et 1 Mo sous iOS, tvOS et Android.

Adresse et port du serveur de contrôle HTTP. Utilisez 127.0.0.1 pour un accès purement local. Se lier à une adresse hors boucle locale (par exemple 192.168.1.5:9090) exige un external-http-secret explicite : sans lui, le serveur refuse de démarrer et journalise ce qui manque.

Une adresse joker (0.0.0.0, ::, *) compte comme hors boucle locale pour cette vérification, car elle écoute sur toutes les interfaces — l'inverse d'un accès local. Les graphies acceptées sont 0.0.0.0:9090, *:9090 (la même chose) et, pour IPv6, [::]:9090 — un :::9090 nu reçoit ses crochets automatiquement ; une adresse impossible à analyser est signalée comme erreur de configuration au lieu de laisser silencieusement le contrôleur éteint. L'ensemble de 127.0.0.0/8 compte comme boucle locale, pas seulement 127.0.0.1.

external-http-secret (par défaut : un jeton généré)

external-http-secret = your-secret-token

Le jeton Bearer utilisé pour l'authentification de l'API. Les requêtes doivent contenir l'en-tête Authorization: Bearer <secret> — le jeton n'est accepté que dans cet en-tête, jamais en paramètre d'URL, et la comparaison se fait en temps constant. Un échec d'authentification renvoie 401 avec {"ok": false, "error": {"code": "unauthorized", "message": "missing or invalid token"}}. Toutes les routes de données sont protégées : les chemins /api/*, les alias compatibles Clash et les routes plus anciennes que seul Chute Android sert encore (/status, /policies, /dns, /records, etc.), qui n'acceptent elles aussi le jeton que dans cet en-tête. Le tableau de bord distant de Chute Android lui-même n'utilise plus que les chemins /api/*. La page et les fichiers statiques de la console web (/, /assets/…, et sur Chute Android aussi /ui) n'ont pas besoin de jeton (avec external-http-ui = false ils disparaissent tout à fait — la page renvoie 404).

Lorsque la clé est absente, Chute génère un jeton au lieu de servir sans authentification. Le jeton généré est écrit dans un fichier control-token du dossier de partage de Chute — pas à côté de la configuration : le conteneur du groupe d'apps sur iOS et tvOS, le répertoire de données privé de l'app sur Android —, lisible par son seul propriétaire, réutilisé d'un redémarrage à l'autre, et les applications vous le montrent — voir Ouvrir la console web. L'API de contrôle peut livrer la base des connexions, dont les enregistrements portent chaque URL, chaque en-tête et chaque nom de processus vus pendant l'exécution ; un contrôleur ouvert n'est pas une valeur par défaut raisonnable.

Si vous voulez malgré tout servir sans authentification, dites-le explicitement dans la configuration :

external-http-secret = none

Cela n'est accepté que pour une liaison en boucle locale. Hors boucle locale, ni none ni l'absence de clé ne suffisent : le serveur de contrôle refuse de démarrer et indique ce qu'il attend.

Mise à niveau : si vous comptiez sur l'absence de external-http-secret pour dire « pas d'authentification », vos scripts locaux commenceront à recevoir 401. Lisez le jeton généré dans l'application, ou écrivez external-http-secret = none pour conserver délibérément l'ancien comportement.

external-http-ui (par défaut : true)

external-http-ui = true

Lorsque cette option est activée, Chute sert une console web intégrée à l'adresse du contrôleur. La console web propose une vue d'ensemble, la gestion des connexions, l'inspection DNS, la surveillance du trafic, les contrôles de politique et l'édition de configuration. Définissez false pour conserver l'API activée tout en désactivant l'interface.

Ouvrir la console web

La console est servie à l'adresse du serveur de contrôle, et chaque application peut vous donner l'adresse et le jeton — y compris celui qui est généré, que vous n'auriez sinon aucun moyen de lire :

• Chute Mac : barre des menus → Ouvrir la console web, et Copier le jeton de la console web. La fenêtre de détail d'une connexion propose aussi Requêtes et historique, qui ouvre la console — sa page d'accueil, pas cette connexion.
• Chute iOS : panneau de configuration → ligne Console web → Ouvrir, Copier l'adresse ou Copier le jeton d'accès.
• Chute tvOS : le panneau de configuration a une ligne distincte Adresse de la console web, qui affiche l'hôte et le port. La sélectionner montre un QR code lorsque l'écouteur est joignable depuis d'autres appareils — le jeton de connexion voyage dans le code, pas à l'écran — et, lorsque le contrôleur est lié à la boucle locale, une explication à la place, car une console en boucle locale ne peut pas s'ouvrir depuis un téléphone.
• Chute Android : panneau de configuration → Adresse de la console web → Ouvrir ou Copier l'adresse, et une ligne Jeton d'accès généré qui copie d'un appui. Aucune des deux lignes n'apparaît lorsque le jeton est un secret que vous avez configuré vous-même, lequel n'est jamais affiché.

L'adresse ainsi produite porte le jeton en paramètre d'URL. La page le consomme au chargement et le retire de la barre d'adresse, si bien qu'ouvrir le lien constitue une connexion complète et que personne n'a à recopier 32 caractères hexadécimaux.

external-http-cors (par défaut : false)

external-http-cors = true

Active les en-têtes CORS (partage de ressources entre origines) sur les réponses de l'API. Utile lorsque la console web ou des outils tiers doivent accéder à l'API depuis une autre origine.

Points de terminaison de l'API :

Notes sur les points de terminaison :

• GET /api/connections accepte limit (entier positif, valeur par défaut et maximale 1000) et cursor (ne renvoie que les connexions dont l'id est supérieur au curseur). Le data de la réponse contient connections, total, page_size, has_more et — lorsque d'autres pages existent — next_cursor.
• GET /api/connections/history accepte limit (par défaut 100, maximum 1000) et cursor/before (synonymes ; les passer tous les deux est rejeté).
• GET /api/connections/:id/request et .../response renvoient {"connection_id": <id>, "data": "<base64>"}. Les captures supérieures à 2 Mio renvoient 413.
• GET /api/config renvoie la configuration avec les valeurs sensibles (http-auth, external-http-secret, ca-p12, ca-passphrase, clés WireGuard et similaires) remplacées par <redacted> — ne réinjectez pas le résultat tel quel dans PUT /api/config, sinon les espaces réservés seraient écrits littéralement dans la configuration.
• GET et PUT /api/config sont aussi accessibles sous /api/configs, ainsi que sous l'alias Clash /configs.
• PUT /api/config accepte soit du JSON {"configuration": "<full text>"}, soit le texte brut de configuration comme corps de requête (limite de 1 Mo). En cas de succès, le moteur se recharge — ou démarre, s'il ne tournait pas.
• PUT /api/policies/:group prend la sélection dans la première des clés de corps policy, name, selected, select ; la valeur peut être un nom de politique ou un index numérique sous forme de chaîne. Le nom de groupe spécial GLOBAL définit la politique globale sélectionnée.
• PUT /api/mode exige un nombre JSON : {"mode": 0} — 0 règles, 1 direct, 2 proxy.
• PUT /api/features/mitm et PUT /api/features/record-traffic prennent {"enabled": true}.
• GET /api/logs accepte since (secondes Unix) ; le tampon en mémoire conserve les 1000 entrées les plus récentes, chacune sous la forme {timestamp, wall_time, level, section, message} — timestamp et wall_time portent la même valeur en secondes Unix, avancée d'un cran quand l'horloge ne progresse pas, afin que les entrées restent strictement ordonnées.
• GET /api/health indique ce que le moteur retient et pourquoi il a refusé quelque chose en dernier, ainsi que la façon dont l'exécution précédente s'est terminée (clean, unclean ou suspected_memory — voir Dépannage).
• GET /api/events sert l'anneau en mémoire ; ?persisted=1 lit à la place l'historique enregistré de cette exécution et répond available: false si l'enregistrement est désactivé.
• Sans section [Tailscale], GET /api/tailscale répond state: "idle" — c'est une réponse normale, pas une erreur.
• Les sondes POST /api/diagnostics/* prennent leurs arguments dans la chaîne de requête ou dans un corps JSON, sont limitées à dix secondes et répondent exactement une fois. url-test/:policy rejette un nom de politique inexistant plutôt que de mesurer REJECT.
• GET /api/scripts liste les scripts génériques activés sous la forme {name, type} ; POST /api/scripts/run prend name dans le corps ou dans la chaîne de requête, est borné comme les sondes de diagnostic, et répond {name, timedOut, result} — timedOut distingue un script qui n'a jamais appelé $done d'un script allé au bout. Un nom qui n'est pas un script générique activé donne un 404.
• POST /api/rules/match répond à la question où irait une requête, sans ouvrir de connexion. Il accepte host (ou une url dont il tire l'hôte et le port ; une règle URL-REGEX est testée sur cette url exactement telle qu'elle est écrite, même si, dans le trafic réel, elle ne voit que des requêtes http:// en clair), port (443 par défaut), et en option ip, protocol, process, process_path, src_ip, src_port, in_port, in_type, in_user, in_name, network, ssid, bssid, from_tun, user_agent — un champ inconnu est refusé avec la liste des champs acceptés, plutôt qu'ignoré. La réponse porte la règle matched (sa ligne, son type, la politique qu'elle nomme et la resolved_policy vers laquelle un groupe pointe actuellement), la policy, need_resolve, ainsi que les rule_count et match_generation sur lesquels le calcul a été fait. Comme un domaine est mis en correspondance deux fois — une fois sur le nom, une seconde fois une fois l'adresse connue —, passes contient une entrée par passe ; sans ip, seule la passe avant résolution existe, et la réponse le dit dans note. Ajoutez explain=true pour obtenir les règles candidates qui auraient pu correspondre aussi, jusqu'à 50, avec le nombre de jeux de règles non dépliés.
• POST /api/config/validate analyse une configuration puis la jette : le moteur en cours n'en adopte rien. Envoyez-la sous la forme {"configuration": "<full text>"} ou en texte brut. La réponse comprend valid, error_count, advisory_count, rule_count, policy_count et une liste errors de {line, severity, content, error} — severity distingue une ligne refusée d'une ligne acceptée avec réserve, et content est la ligne fautive, expurgée, car une mauvaise ligne [Proxy] porte le plus souvent le mot de passe qui l'a rendue mauvaise. Servez-vous-en avant PUT /api/config, qui redémarre l'exécution que vous êtes en train de déboguer.
• GET /api/loglevel indique le level courant, le nslog_level, les sections écrites dans le fichier, et les available_levels / available_sections que vous pouvez définir. PUT (ou PATCH) accepte level, sections, ou les deux : sections est un tableau de noms de sections ou la chaîne "all", et un tableau vide est refusé — pour arrêter la journalisation, utilisez level avec none. Changer le niveau ainsi ne redémarre pas l'exécution, et c'est bien l'intérêt : loglevel = verbose dans le fichier exige un rechargement, et un rechargement perd précisément ce que vous cherchiez à voir.
• GET /api/rules renvoie aussi rewrite_hits : chaque règle de réécriture ou de réponse simulée qui a agi pendant cette exécution, avec son compteur. Une règle absente de cette liste n'a jamais correspondu — c'est l'explication habituelle d'une réécriture qui semble ne rien faire. Le tableau suit jusqu'à 512 règles distinctes et signale tout ce qui dépasse dans rewrite_hit_dropped_rules. rules liste dans l'ordre chaque règle que parcourt le moteur : les règles Tailscale automatiques, puis les règles des modules, puis la section [Rule] de la configuration, et enfin FINAL ; rule_regions indique l'origine de chaque ligne, indice pour indice (front, module, configuration).
• POST /api/rewrites/:family prend {"rule": "<configuration line>"} — exactement le texte que vous écririez dans le fichier. Une ligne qui ne s'analyse pas est refusée avec 400 au lieu d'être stockée comme une règle qui ne pourra jamais correspondre. :family vaut url-rewrite, header-rewrite, body-rewrite ou mock. Les règles ajoutées ainsi vivent dans le moteur en cours d'exécution et ne sont pas réécrites dans le fichier de configuration.
• GET /api/connections/export?format=har renvoie un document HAR 1.2 et POST /api/diagnostics/bundle un zip — ce sont des fichiers, donc contrairement à tous les autres points d'accès ils ne sont pas enveloppés dans {"ok": ..., "data": ...}. export accepte source (current par défaut, ou history), limit (100 par défaut, 300 au maximum), ids, et bodies=1 pour inclure les charges utiles capturées. Chaque entrée porte un objet _kl avec ce dont HAR n'a pas de champ : la politique choisie, la règle correspondante et les réécritures qui ont agi.
• L'enregistrement d'une connexion chaînée dans GET /api/connections et GET /api/connections/history porte chainPath, le chemin de cet appareil jusqu'à la sortie, comme Airport/HK-01 → Landing ; il est vide pour une connexion qui n'a utilisé qu'une politique, et l'export HAR le porte sous _kl.chain. Dans les compteurs par politique de GET /api/traffic, un amont compte aussi les octets qu'il a transportés pour des connexions chaînées ; les totaux globaux ne les comptent qu'une fois.

Exemple — lire l'état, puis changer un groupe de politiques :

curl -H "Authorization: Bearer your-secret-token" http://127.0.0.1:9090/api/status
{"ok":true,"data":{"running":true,"outbound_mode":0,"mitm":false, ...}}

curl -X PUT -H "Authorization: Bearer your-secret-token" \
     -d '{"policy": "ProxyB"}' http://127.0.0.1:9090/api/policies/MainGroup
{"ok":true,"data":{"outbound_mode":0,"selectable_groups":[...], ...}}

Exemple — demander où irait une requête, avant de l'émettre :

curl -X POST -H "Authorization: Bearer your-secret-token" \
     -d '{"url": "https://api.example.com/v1/orders", "explain": true}' \
     http://127.0.0.1:9090/api/rules/match
{"ok":true,"data":{"policy":"MainGroup","matched":{"rule":"DOMAIN-SUFFIX,example.com,MainGroup", ...}, ...}}

Restreindre le journal à un sous-système pendant la reproduction, sans redémarrer l'exécution :

curl -X PUT -H "Authorization: Bearer your-secret-token" \
     -d '{"level": "verbose", "sections": ["MitM", "DNS"]}' \
     http://127.0.0.1:9090/api/loglevel

Remarque : cette fonctionnalité est désactivée par défaut. Chaque réponse utilise l'enveloppe {"ok": true, "data": {...}} en cas de succès et {"ok": false, "error": {"code": "...", "message": "..."}} en cas d'erreur ; les corps de requête sont limités à 1 Mo.

Les points de terminaison PUT acceptent également PATCH. Des chemins d'alias compatibles Clash sont disponibles pour les tableaux de bord tiers : /version, /traffic, /connections, /configs, /proxies, /rules — ces chemins sont accessibles, mais les réponses utilisent l'enveloppe et les noms de champ de Chute plutôt que le schéma de Clash (/version renvoie {"name", "run_id", "egress_probe"}, où egress_probe vaut network_address sur les moteurs Apple et egress_ip sur Android) ; les tableaux de bord Clash ne fonctionneront donc pas tels quels.

URL de test du proxy

[General]
proxy-test-url = http://cp.cloudflare.com/generate_204
test-timeout = 3

proxy-test-url est l'URL de test de chaque groupe url-test, fallback et load-balance qui ne définit pas son propre url, et test-timeout (secondes) le délai de chaque groupe de ce type sans timeout. Les groupes continuent de suivre ces clés après l'enregistrement de la configuration ; seul un url ou un timeout écrit sur la ligne du groupe les remplace. Une proxy-test-url invalide est une erreur de configuration. internet-test-url est utilisé par le test Internet direct de la console web et est récupéré sans proxy ; s'il est absent, le moteur utilise son URL de réussite intégrée.

UDP via une politique sans UDP

udp-policy-not-supported-behaviour = DIRECT

Ce qu'il advient d'un datagramme UDP dont la politique ne peut pas relayer l'UDP, comme un simple proxy HTTP : REJECT (par défaut) l'abandonne ; DIRECT l'envoie directement à la place. block-quic est tranché avant, sur la politique choisie par la règle : avec block-quic = auto, le QUIC destiné à un proxy qui ne peut pas relayer l'UDP est rejeté au lieu d'être envoyé directement. Le reste de l'UDP se rabat toujours sur DIRECT. L'UDP d'une politique chaînée qui ne peut pas passer par son amont est traité de la même façon, tout comme un serveur DoQ ou DoH3 qui suit le mode de sortie vers une politique sans UDP : REJECT ignore ce serveur, DIRECT l'interroge directement.

Proxy frontal

[General]
global-underlying-proxy = Airport

Fait passer chaque politique de proxy sans underlying-proxy propre par la politique ou le groupe nommé — ce que Shadowrocket appelle proxy frontal (前置代理) et ne règle que dans son app. Les politiques des fournisseurs de proxy sont incluses. Restent inchangés : toute politique qu'une connexion par la politique frontale elle-même peut traverser — ses membres, leurs amonts et les sauts d'un relais parmi eux —, afin que la politique frontale ne passe jamais par elle-même ; une politique qui écrit underlying-proxy=DIRECT, ce qui l'exclut ; les groupes de politiques, dont les membres décident ; et DIRECT, REJECT et TAILSCALE. Omettez la clé, ou écrivez DIRECT, pour la désactiver. Un nom non défini refuse toutes les politiques qu'il couvrirait au lieu de les laisser se connecter directement.

close-if-proxy-chain-missing (Shadowrocket) est lu et réécrit à l'enregistrement du profil. Chute se comporte toujours comme avec true : une politique chaînée dont l'amont manque est refusée. false — la valeur par défaut de Shadowrocket, qui saute le saut manquant et connecte le nœud directement — n'est pas suivi, et un avis le signale une fois.

Empreinte du client

global-client-fingerprint = chrome

Définit l'empreinte du client TLS pour toute politique qui n'a pas la sienne (fingerprint), y compris les politiques que fournit un fournisseur de proxy. La valeur propre à une politique l'emporte toujours ; il s'agit donc d'une valeur par défaut, et non d'un remplacement.

Les valeurs prises en charge sont chrome, firefox, safari et ios, ainsi que edge, 360, qq, android et random, toutes traitées comme Chrome, ainsi que les autres noms cités sous fingerprint. Une valeur non reconnue est ignorée avec l'avertissement Ignoring unsupported global-client-fingerprint '<value>', et la pile TLS de la plateforme est utilisée.

Par défaut : vide, ce qui signifie la pile TLS de la plateforme. Les politiques ShadowTLS la lisent toujours ; les politiques VLESS la lisent si elles définissent tls=true ou reality=true, les politiques Trojan et VMess si elles définissent tls=true, et les politiques Shadowsocks si elles définissent à la fois ws=true et tls=true ; une politique sur le transport gRPC doit elle aussi écrire tls=true. Les politiques ShadowsocksR ne la lisent jamais.