모듈

Chute는 재사용 및 공유 가능한 규칙, 스크립트, MitM 호스트, DNS 매핑으로 구성을 확장하기 위해 외부 모듈 파일(.sgmodule)을 지원합니다. 모듈은 Surge 모듈 형식을 따릅니다.

모듈은 [Module] 섹션에 정의됩니다:

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

http://와 https:// 모듈은 원격에서 가져오며, 로컬 파일은 스킴 없이 경로만 적습니다 — /path/to/local-module.sgmodule 또는 ~/.chute/local-module.sgmodule — 구성을 다시 저장할 때 기록되는 형태도 이것입니다. file:/// URL로 적어도 동작합니다. 읽을 수 없는 로컬 모듈 파일은 로그에 경고를 남기고 건너뜁니다.

모듈 파일 구조

.sgmodule 파일은 기본 구성 파일과 동일한 구문을 따릅니다. 지원되는 섹션:

호환성을 위해 모듈의 [DNS] 섹션은 [Host]의 별칭으로 허용됩니다.

모듈 메타데이터

모듈은 메타데이터 지시문(#!로 시작하는 줄)을 포함할 수 있습니다:

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

#!system은 모듈 편집기에 표시되는 정보성 메타데이터입니다. 현재는 로드를 제한하지 않으며, 모듈은 모든 플랫폼에서 적용됩니다.

#!arguments는 여러 번 나타날 수 있으며, 뒤에 선언된 것이 앞의 것을 덮어씁니다. 모듈 본문의 {{{variable}}} 자리 표시자는 그 변수의 #!arguments 기본값으로 치환되며, 기본값을 선언하지 않았다면 빈 문자열로 치환됩니다. 현재 모듈 인자를 재정의하는 방법을 제공하는 앱은 없으므로, 언제나 선언된 기본값이 적용됩니다.

#!IOS-ONLY, #!MACOS-ONLY, #!TVOS-ONLY를 앞에 붙인 줄은 해당 플랫폼에서만 적용되고 다른 곳에서는 제외됩니다 — 모듈 안이든 구성 파일 자체든 어디에 있어도 마찬가지입니다.

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

앱이 구성을 저장할 때 접두사는 쓰인 그대로 유지됩니다. 이 플랫폼에서 제외된 줄은 파일에서 사라지지도, 주석으로 바뀌지도 않으므로 같은 프로필이 다른 플랫폼에서 계속 동작합니다.

모듈 예제

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

모듈의 hostname 값에 포함된 %APPEND% / %INSERT% 지시문은 제거되고 호스트명은 MitM 목록에 병합됩니다. 호스트명 앞에 붙은 - 제외 접두사는 유지됩니다.

모듈의 [General] 섹션은 %APPEND%(끝에 추가) 또는 %INSERT%(앞에 추가)로 실행 중인 구성의 목록형 옵션 다섯 가지(skip-proxy, tun-excluded-routes, tun-included-routes, dns-server, always-real-ip)를 확장할 수 있습니다. 병합은 다섯 가지 모두에서 이루어집니다. 두 라우트 목록을 어느 플랫폼의 터널이 읽는지는 포함 라우트와 제외 라우트에 설명되어 있습니다. 값은 모듈을 적용할 때 병합되고, 모듈을 제거하거나 비활성화하면 철회됩니다. 목록 전체 교체는 지원되지 않으므로 지시문이 없는 값도 알림과 함께 끝에 추가되며, 그 밖의 [General] 키는 알림과 함께 무시됩니다.

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

모듈 생명주기

• 모듈은 기본 구성이 파싱된 후 로드됩니다.
• 모듈의 규칙, 스크립트, MitM 호스트 및 DNS 호스트가 런타임 관리자에 추가됩니다.
• 모듈의 [Rule] 줄은 Tailscale 자동 규칙 뒤, 구성 자체의 규칙 앞에 모듈 로드 순서대로 놓입니다. Surge와 같으며, 광고 차단 모듈의 REJECT가 구성의 앞선 규칙에 가려지지 않습니다.
• 모듈의 [Map Local], [Body Rewrite], [General] 병합은 구성을 다시 로드한 뒤 다시 적용됩니다.
• 모듈이 제거되거나 비활성화되면 해당 모듈의 모든 규칙, 스크립트 및 호스트가 등록 해제됩니다.
• 원격 모듈 콘텐츠는 터널이 시작될 때 가져오며, 구성 재로드 시 [Module] URL 목록이 변경된 경우에만 다시 가져옵니다.