github.com/yaling888/clash@v1.53.0/README.md (about) 1 <h1 align="center"> 2 <img src="https://github.com/yaling888/clash/raw/plus-pro/docs/logo.png" alt="Clash" width="200"> 3 <br>Clash<br> 4 </h1> 5 6 <h4 align="center">A rule-based tunnel in Go.</h4> 7 8 <p align="center"> 9 <a href="https://github.com/yaling888/clash/actions"> 10 <img src="https://img.shields.io/github/actions/workflow/status/yaling888/clash/release.yml?branch=plus-pro&style=flat-square" alt="Github Actions"> 11 </a> 12 <a href="https://goreportcard.com/report/github.com/yaling888/clash"> 13 <img src="https://goreportcard.com/badge/github.com/yaling888/clash?style=flat-square"> 14 </a> 15 <img src="https://img.shields.io/github/go-mod/go-version/yaling888/clash/plus-pro?style=flat-square"> 16 <a href="https://github.com/yaling888/clash/releases"> 17 <img src="https://img.shields.io/github/release/yaling888/clash/all.svg?style=flat-square"> 18 </a> 19 </p> 20 21 ## Features 22 23 - Local HTTP/HTTPS/SOCKS server with authentication support 24 - Shadowsocks(R), VMess, VLESS, Trojan, Snell, WireGuard, SOCKS5, HTTP(S) outbound support 25 - Built-in [fake-ip](https://www.rfc-editor.org/rfc/rfc3089) DNS server that aims to minimize DNS pollution attack impact. DoH/DoT upstream supported. 26 - Rules based off dynamic scripting, domains, GEOIP, GEOSITE, IP-CIDR or process names to route packets to different destinations 27 - Proxy groups allow users to implement powerful rules. Supports automatic fallback, load balancing or auto select proxy based off latency 28 - Remote providers, allowing users to get proxy lists remotely instead of hardcoding in config 29 - Transparent proxy: Redirect TCP and TProxy TCP/UDP with automatic route table/rule management 30 - Hot-reload via the comprehensive HTTP RESTful API controller 31 - System/gVisor stack TUN device on macOS, Linux and Windows 32 - Policy routing with Scripts 33 34 ## Getting Started 35 Documentations are available at [GitHub Wiki](https://yaling888.github.io/clash/). 36 37 ## Advanced usage for this branch 38 ### General configuration 39 ```yaml 40 # sniffing: true # Sniff TLS SNI 41 42 force-cert-verify: true # force verify TLS Certificate for all proxies, prevent Machine-In-The-Middle attack 43 44 profile: 45 tracing: false # prevent logs leak, default value is true 46 47 experimental: 48 udp-fallback-policy: 'a proxy that supports UDP' # or `direct` or `reject` 49 ``` 50 51 ### MITM configuration 52 A root CA certificate is required, the 53 MITM proxy server will generate a CA certificate file and a CA private key file in your Clash home directory, you can use your own certificate replace it. 54 55 Need to install and trust the CA certificate on the client device, open this URL [http://mitm.clash/cert.crt](http://mitm.clash/cert.crt) by the web browser to install the CA certificate, the host name 'mitm.clash' was always been hijacked. 56 57 NOTE: this feature cannot work on tls pinning 58 59 WARNING: DO NOT USE THIS FEATURE TO BREAK LOCAL LAWS 60 61 ```yaml 62 # Port of MITM proxy server on the local end 63 mitm-port: 7894 64 65 # Machine-In-The-Middle attack 66 mitm: 67 hosts: # use for others proxy type. E.g: TUN, socks 68 - +.example.com 69 rules: # rewrite rules 70 - '^https?://www\.example\.com/1 url reject' # The "reject" returns HTTP status code 404 with no content. 71 - '^https?://www\.example\.com/2 url reject-200' # The "reject-200" returns HTTP status code 200 with no content. 72 - '^https?://www\.example\.com/3 url reject-img' # The "reject-img" returns HTTP status code 200 with content of 1px png. 73 - '^https?://www\.example\.com/4 url reject-dict' # The "reject-dict" returns HTTP status code 200 with content of empty json object. 74 - '^https?://www\.example\.com/5 url reject-array' # The "reject-array" returns HTTP status code 200 with content of empty json array. 75 - '^https?://www\.example\.com/(6) url 302 https://www.example.com/new-$1' 76 - '^https?://www\.(example)\.com/7 url 307 https://www.$1.com/new-7' 77 - '^https?://www\.example\.com/8 url request-header (\r\n)User-Agent:.+(\r\n) request-header $1User-Agent: haha-wriohoh$2' # The "request-header" works for all the http headers not just one single header, so you can match two or more headers including CRLF in one regular expression. 78 - '^https?://www\.example\.com/9 url request-body "pos_2":\[.*\],"pos_3" request-body "pos_2":[{"xx": "xx"}],"pos_3"' 79 - '^https?://www\.example\.com/10 url response-header (\r\n)Tracecode:.+(\r\n) response-header $1Tracecode: 88888888888$2' 80 - '^https?://www\.example\.com/11 url response-body "errmsg":"ok" response-body "errmsg":"not-ok"' 81 ``` 82 83 ### DNS configuration 84 Support lookup ip with a proxy tunnel or interface. 85 86 Support `geosite` with `fallback-filter`. 87 88 Use `curl -X POST controllerip:port/cache/fakeip/flush` to flush persistence fakeip 89 ```yaml 90 dns: 91 enable: true 92 use-hosts: true 93 ipv6: false 94 remote-dns-resolve: true # remote resolve DNS on handle TCP connect and UDP session, default value is true 95 enhanced-mode: fake-ip 96 fake-ip-range: 198.18.0.1/16 97 listen: 127.0.0.1:6868 98 default-nameserver: 99 - 119.29.29.29 100 - 114.114.114.114 101 nameserver: 102 - https://doh.pub/dns-query 103 - tls://223.5.5.5:853 104 fallback: 105 - 'tls://8.8.4.4:853#proxy or interface' 106 - 'https://1.0.0.1/dns-query#Proxy' # use a proxy or interface 107 remote-nameserver: # remote resolve DNS 108 - 'tls://1.1.1.1:853' 109 - 'tls://8.8.8.8:853' 110 fallback-filter: 111 geoip: false 112 geosite: 113 - gfw # `geosite` filter only use fallback server to lookup ip, prevent DNS leaks to untrusted DNS providers. 114 domain: 115 - +.example.com 116 ipcidr: 117 - 0.0.0.0/32 118 ``` 119 120 ### TUN configuration 121 Simply add the following to the main configuration: 122 123 #### NOTE: 124 > auto-route and auto-detect-interface only available on macOS, Windows and Linux, receive IPv4 traffic 125 126 ```yaml 127 tun: 128 enable: true 129 stack: system # or gvisor 130 # dns-hijack: 131 # - 8.8.8.8:53 132 # - tcp://8.8.8.8:53 133 # - any:53 134 # - tcp://any:53 135 auto-route: true # auto set global route 136 auto-detect-interface: true # conflict with interface-name 137 ``` 138 or 139 ```yaml 140 interface-name: en0 141 142 tun: 143 enable: true 144 stack: system # or gvisor 145 # dns-hijack: 146 # - 8.8.8.8:53 147 # - tcp://8.8.8.8:53 148 auto-route: true # auto set global route 149 ``` 150 It's recommended to use fake-ip mode for the DNS server. 151 152 Clash needs elevated permission to create TUN device: 153 ```sh 154 $ sudo ./clash 155 ``` 156 Then manually create the default route and DNS server. If your device already has some TUN device, Clash TUN might not work. In this case, fake-ip-filter may helpful. 157 158 Enjoy! :) 159 160 #### For Windows: 161 ```yaml 162 tun: 163 enable: true 164 stack: gvisor # or system 165 dns-hijack: 166 - 198.18.0.2:53 # when `fake-ip-range` is 198.18.0.1/16, should hijack 198.18.0.2:53 167 auto-route: true # auto set global route for Windows 168 # It is recommended to use `interface-name` 169 auto-detect-interface: true # auto detect interface, conflict with `interface-name` 170 ``` 171 Finally, open the Clash 172 173 ### Rules configuration 174 - Support rule `SCRIPT` shortcuts. 175 - Support rule `GEOSITE`. 176 - Support rule `USER-AGENT`. 177 - Support `multiport` condition for rule `SRC-PORT` and `DST-PORT`. 178 - Support nestable "rule groups", `if` field is the same as the shortcut syntax and if none of the sub-rules match, then continue to match the next rule. 179 180 Script shortcuts engines: [expr](https://expr-lang.org/) & [starlark](https://github.com/google/starlark-go). 181 182 ```yaml 183 mode: rule 184 185 script: 186 engine: expr # or starlark (10x to 20x slower), the default engine is `expr` 187 shortcuts: # `src_port` and `dst_port` are number 188 quic: 'network == "udp" and dst_port == 443' 189 # privacy: '"analytics" in host or "adservice" in host or "firebase" in host or "safebrowsing" in host or "doubleclick" in host' 190 privacy: | 191 any(["analytics", "adservice", "firebase", "safebrowsing", "doubleclick", "bugly", "bugsnag"], host contains #) 192 BilibiliUdp: | 193 network == "udp" and match_provider("bilibili") 194 ParentalControls: | 195 src_ip == "192.168.1.123" and now.hour < 8 and now.hour > 22 196 rules: 197 - if: network == 'tcp' 198 name: TCP 199 # engine: expr # the default engine is `expr`, `starlark` is also valid 200 rules: 201 - if: dst_port == 443 202 name: HTTPS 203 rules: 204 - MATCH,DIRECT 205 - DOMAIN-SUFFIX,baidu.com,DIRECT 206 207 # rule SCRIPT shortcuts 208 - SCRIPT,quic,REJECT # Disable QUIC 209 - SCRIPT,privacy,REJECT 210 - SCRIPT,BilibiliUdp,REJECT 211 - SCRIPT,ParentalControls,REJECT 212 213 # multiport condition for rules SRC-PORT and DST-PORT 214 - DST-PORT,123/136/137-139,DIRECT,udp 215 216 # USER-AGENT payload cannot include the comma character, '*' meaning any character. 217 # - USER-AGENT,*example*,PROXY 218 219 # rule GEOSITE 220 - GEOSITE,category-ads-all,REJECT 221 - GEOSITE,icloud@cn,DIRECT 222 - GEOSITE,apple@cn,DIRECT 223 - GEOSITE,apple-cn,DIRECT 224 - GEOSITE,microsoft@cn,DIRECT 225 - GEOSITE,facebook,PROXY 226 - GEOSITE,youtube,PROXY 227 - GEOSITE,geolocation-cn,DIRECT 228 - GEOSITE,geolocation-!cn,PROXY 229 230 - GEOIP,telegram,PROXY,no-resolve 231 - GEOIP,lan,DIRECT,no-resolve 232 - GEOIP,cn,DIRECT 233 234 - MATCH,PROXY 235 ``` 236 Script shortcut parameters 237 ```ts 238 now: { 239 year: int 240 month: int 241 day: int 242 hour: int 243 minute: int 244 second: int 245 } 246 type: string 247 network: string 248 host: string 249 process_name: string 250 process_path: string 251 user_agent: string 252 special_proxy: string 253 src_ip: string 254 src_port: uint16 255 dst_ip: string // call resolve_ip(host) if empty 256 dst_port: uint16 257 inbound_port: uint16 258 ``` 259 Script shortcut functions 260 ```ts 261 type resolve_ip = (host: string) => string // ip string 262 type in_cidr = (ip: string, cidr: string) => boolean // ip in cidr 263 type in_ipset = (name: string, ip: string) => boolean // ip in ipset 264 type geoip = (ip: string) => string // country code 265 type match_provider = (name: string) => boolean // in rule provider 266 type resolve_process_name = () => string // process name 267 type resolve_process_path = () => string // process path 268 ``` 269 270 ### Script configuration 271 Script enables users to programmatically select a policy for the packets with more flexibility. 272 273 NOTE: If you want to use `ctx.geoip(ip)` you need to manually resolve ip first. 274 275 ```yaml 276 mode: script 277 278 script: 279 # path: ./script.star 280 code: | 281 def main(ctx, metadata): 282 processName = ctx.resolve_process_name(metadata) 283 if processName == 'apsd': 284 return "DIRECT" 285 286 if metadata["network"] == 'udp' and metadata["dst_port"] == '443': 287 return "REJECT" 288 289 host = metadata["host"] 290 for kw in ['analytics', 'adservice', 'firebase', 'bugly', 'safebrowsing', 'doubleclick']: 291 if kw in host: 292 return "REJECT" 293 294 # now = time.now() 295 # if (now.hour < 8 or now.hour > 18) and metadata["src_ip"] == '192.168.1.99': 296 # return "REJECT" 297 298 if ctx.rule_providers["category-ads-all"].match(metadata): 299 return "REJECT" 300 301 if ctx.rule_providers["youtube"].match(metadata): 302 ctx.log('[Script] domain %s matched youtube' % host) 303 return "Proxy" 304 305 if ctx.rule_providers["geolocation-cn"].match(metadata): 306 ctx.log('[Script] domain %s matched geolocation-cn' % host) 307 return "DIRECT" 308 309 ip = metadata["dst_ip"] 310 if ip == "": 311 ip = ctx.resolve_ip(host) 312 if ip == "": 313 return "Proxy" 314 315 code = ctx.geoip(ip) 316 if code == "TELEGRAM": 317 ctx.log('[Script] matched telegram') 318 return "Proxy" 319 320 if code == "CN" or code == "LAN" or code == "PRIVATE": 321 return "DIRECT" 322 323 return "Proxy" # default policy for requests which are not matched by any other script 324 ``` 325 the context and metadata 326 ```ts 327 interface Metadata { 328 type: string // socks5、http 329 network: string // tcp、udp 330 host: string 331 user_agent: string 332 special_proxy: string 333 src_ip: string 334 src_port: string 335 dst_ip: string 336 dst_port: string 337 inbound_port: number 338 } 339 340 interface Context { 341 resolve_ip: (host: string) => string // ip string 342 resolve_process_name: (metadata: Metadata) => string 343 resolve_process_path: (metadata: Metadata) => string 344 geoip: (ip: string) => string // country code 345 log: (log: string) => void 346 proxy_providers: Record<string, Array<{ name: string, alive: boolean, delay: number }>> 347 rule_providers: Record<string, { match: (metadata: Metadata) => boolean }> 348 } 349 ``` 350 351 ### Proxies configuration 352 Support outbound protocol `VLESS`. 353 354 Support userspace `WireGuard` outbound. 355 356 Support relay `UDP` traffic. 357 358 Support filtering proxy providers in proxy groups. 359 360 Support custom http request header, prefix name and V2Ray subscription URL in proxy providers. 361 ```yaml 362 proxies: 363 # VLESS 364 - name: "vless-tls" 365 type: vless 366 server: server 367 port: 443 368 uuid: uuid 369 network: tcp 370 servername: example.com 371 udp: true 372 # skip-cert-verify: true 373 374 # WireGuard 375 - name: "wg" 376 type: wireguard 377 server: 127.0.0.1 378 port: 443 379 ip: 127.0.0.1 380 # ipv6: your_ipv6 381 private-key: eCtXsJZ27+4PbhDkHnB923tkUn2Gj59wZw5wFA75MnU= 382 public-key: Cr8hWlKvtDt7nrvf+f0brNQQzabAqrjfBvas9pmowjo= 383 # preshared-key: base64 384 # remote-dns-resolve: true # remote resolve DNS with `dns` field, default is true 385 # dns: [1.1.1.1, 8.8.8.8] 386 # mtu: 1420 387 udp: true 388 389 # Trojan QUIC 390 - name: "trojan-quic" 391 type: trojan 392 server: server 393 port: 443 394 password: password 395 udp: true 396 alpn: 397 - h3 398 sni: example.com 399 network: quic 400 quic-opts: 401 cipher: none # aes-128-gcm / chacha20-poly1305 402 key: your_key 403 obfs: none # srtp / utp / dtls / wechat-video / wireguard 404 405 # VMess QUIC 406 - name: "vmess-quic" 407 type: vmess 408 server: server 409 port: 443 410 uuid: uuid 411 alterId: 0 412 cipher: auto 413 udp: true 414 tls: true 415 alpn: 416 - h3 417 servername: example.com 418 network: quic 419 quic-opts: 420 cipher: none # aes-128-gcm / chacha20-poly1305 421 key: your_key 422 obfs: none # srtp / utp / dtls / wechat-video / wireguard 423 424 proxy-groups: 425 # Relay chains the proxies. proxies shall not contain a relay. 426 # Support relay UDP traffic. 427 # Traffic: clash <-> ss1 <-> trojan <-> vmess <-> ss2 <-> Internet 428 - name: "relay-udp-over-tcp" 429 type: relay 430 proxies: 431 - ss1 432 - trojan 433 - vmess 434 - ss2 435 436 - name: "relay-raw-udp" 437 type: relay 438 proxies: 439 - ss1 440 - ss2 441 - ss3 442 443 - name: "filtering-proxy-providers" 444 type: url-test 445 url: "http://www.gstatic.com/generate_204" 446 interval: 5m # support human-friendly config (30s 1h 10m30s etc.) 447 tolerance: 200ms # support human-friendly config (30s 1h 10m30s etc.) 448 # lazy: true 449 # disable-dns: true # disable remote resolve DNS for this group 450 filter: "XXX" # a regular expression 451 use: 452 - provider1 453 454 proxy-providers: 455 provider1: 456 type: http 457 url: "url" 458 interval: 24h # support human-friendly config (30s 1h 10m30s etc.) 459 path: ./providers/provider1.yaml 460 # prefix-name: "XXX-" # append a prefix name to each proxy name to avoid duplicate names with other proxies 461 # url-proxy: true # proxy the URL by inbounds or TUN 462 # rand-host: true # use a random host for http/ws network, it will overwrite the `host` field in http-opts and ws-opts 463 # disable-dns: true # disable remote resolve DNS 464 # udp: true # force enable UDP traffic, it will overwrite the `udp` field, conflict with `disable-udp` field 465 # disable-udp: true # disable UDP traffic, it will overwrite the `udp` field 466 force-cert-verify: true # force verify TLS Certificate, default value is true, if the value is true then overwrite the `skip-cert-verify` value to false 467 # header: # custom http request header 468 # User-Agent: 469 # - "Clash/v1.18.0" 470 # Accept: 471 # - 'application/vnd.github.v3.raw' 472 # Authorization: 473 # - ' token xxxxxxxxxxx' 474 health-check: 475 enable: false 476 interval: 0 477 # lazy: false # default value is true 478 url: http://www.gstatic.com/generate_204 479 ``` 480 481 ### Tunnels configuration 482 tunnels (like SSH local forwarding). 483 ```yaml 484 tunnels: 485 # one line config 486 - tcp/udp,127.0.0.1:6553,114.114.114.114:53,proxy 487 - tcp,127.0.0.1:6666,rds.mysql.com:3306,vpn 488 # full yaml config 489 - network: [tcp, udp] 490 address: 127.0.0.1:7777 491 target: target.com 492 proxy: proxy 493 ``` 494 495 ### eBPF 496 It requires Linux kernel version >= 4.5, support `redirect-to-tun` and `auto-redir` features. 497 498 #### redirect-to-tun: 499 only hook traffic of the egress NIC, conflict with `auto-route` and `auto-redir`. 500 ```yaml 501 interface-name: eth0 502 503 ebpf: 504 redirect-to-tun: 505 - eth0 506 507 tun: 508 enable: true 509 stack: system 510 dns-hijack: 511 - any:53 512 auto-route: false 513 ``` 514 515 #### auto-redir: 516 only hook TCP traffic of the ingress NIC and conflict with `redirect-to-tun`, It can be replaced with redir-port (TCP) without any network config. 517 518 It's recommended to work with TUN to handle UDP traffic. It improves the network throughput performance of some low performance devices compared to using exclusively TUN. 519 ```yaml 520 interface-name: eth0 521 522 ebpf: 523 auto-redir: 524 - eth0 525 # - wlan0 526 527 tun: 528 enable: true 529 stack: system 530 dns-hijack: 531 - any:53 532 auto-route: true 533 ``` 534 535 ### Template 536 * [General](https://github.com/yaling888/clash/blob/plus-pro/examples/template/local-client.yaml), usually used as a local client. 537 * [Auto redirect](https://github.com/yaling888/clash/blob/plus-pro/examples/template/auto-redir-transparent-gateway.yaml), usually used as a transparent proxy gateway. 538 * [Redirect to tun](https://github.com/yaling888/clash/blob/plus-pro/examples/template/redirect-to-tun-transparent-gateway.yaml), usually used as a transparent proxy gateway. 539 540 ### Daemon 541 * For [macOS](https://github.com/yaling888/clash/blob/plus-pro/examples/daemon/macos/org.eu.clashplus.plist). 542 * For [Linux](https://github.com/yaling888/clash/blob/plus-pro/examples/daemon/linux/clash.service). 543 * For [Windows](https://github.com/yaling888/SoulX). 544 545 ### Web GUI 546 Open the Dashboard online by click [http://yacd.eu.org](http://yacd.eu.org) for local API by Safari or [https://yacd.eu.org](https://yacd.eu.org) for local API by Chrome. 547 548 You can download the [Dashboard](https://github.com/yaling888/yacd/archive/gh-pages.zip) into Clash home directory: 549 ```sh 550 mkdir -p ~/.config/clash && \ 551 cd ~/.config/clash && \ 552 curl -LJ https://github.com/yaling888/yacd/archive/gh-pages.zip -o yacd-gh-pages.zip && \ 553 unzip yacd-gh-pages.zip && \ 554 rm -rf dashboard/ yacd-gh-pages.zip && \ 555 mv yacd-gh-pages dashboard 556 ``` 557 558 Add to config file: 559 ```yaml 560 external-controller: 127.0.0.1:9090 561 external-ui: dashboard 562 ``` 563 Open [http://127.0.0.1:9090/ui/](http://127.0.0.1:9090/ui/) by web browser. 564 565 ### Set up a free tunnel server on Cloudflare Workers 566 **NOTE**: The Cloudflare Workers outbound TCP sockets to [Cloudflare IP ranges](https://www.cloudflare.com/ips/) are temporarily blocked and the outbound UDP is not supported. 567 568 1. Create a Cloudflare Worker application. 569 2. Set up a custom domain for your Worker application. 570 3. Check the repository [Trovle](https://github.com/yaling888/trovle), the transport `Trojan` and `VLESS` are supported. 571 4. Copy [worker.js](https://github.com/yaling888/trovle/blob/main/worker.js) content into your Worker application. 572 5. Edit the `configs`, modify the uuid and password. 573 6. Save and deploy. 574 575 ## Credits 576 577 * [riobard/go-shadowsocks2](https://github.com/riobard/go-shadowsocks2) 578 * [v2ray/v2ray-core](https://github.com/v2ray/v2ray-core) 579 * [WireGuard/wireguard-go](https://github.com/WireGuard/wireguard-go)