history-museum/clash
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Docs: new documentation site (#2723)

Browse Source 
This commit adds a VitePress build to the main repository,
aiming to ditch GitHub Wiki. Moving further, we're going to
host our own documentation site eithor on GitHub Pages or
something alike.
This commit is contained in:
Birkhoff Lee
2023-05-15 21:47:01 +08:00
committed by GitHub
parent 10dcb7a3ad
commit ca42ca2ca8
30 changed files with 2477 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

480
docs/configuration/configuration-reference.md Normal file
View File

@ -0,0 +1,480 @@
---
sidebarTitle: Configuration Reference
sidebarOrder: 7
---
# Configuration Reference
```yaml
# Port of HTTP(S) proxy server on the local end
port: 7890
# Port of SOCKS5 proxy server on the local end
socks-port: 7891
# Transparent proxy server port for Linux and macOS (Redirect TCP and TProxy UDP)
# redir-port: 7892
# Transparent proxy server port for Linux (TProxy TCP and TProxy UDP)
# tproxy-port: 7893
# HTTP(S) and SOCKS4(A)/SOCKS5 server on the same port
# mixed-port: 7890
# authentication of local SOCKS5/HTTP(S) server
# authentication:
# - "user1:pass1"
# - "user2:pass2"
# Set to true to allow connections to the local-end server from
# other LAN IP addresses
# allow-lan: false
# This is only applicable when `allow-lan` is `true`
# '*': bind all IP addresses
# 192.168.122.11: bind a single IPv4 address
# "[aaaa::a8aa:ff:fe09:57d8]": bind a single IPv6 address
# bind-address: '*'
# Clash router working mode
# rule: rule-based packet routing
# global: all packets will be forwarded to a single endpoint
# direct: directly forward the packets to the Internet
mode: rule
# Clash by default prints logs to STDOUT
# info / warning / error / debug / silent
# log-level: info
# When set to false, resolver won't translate hostnames to IPv6 addresses
# ipv6: false
# RESTful web API listening address
external-controller: 127.0.0.1:9090
# A relative path to the configuration directory or an absolute path to a
# directory in which you put some static web resource. Clash core will then
# serve it at `http://{{external-controller}}/ui`.
# external-ui: folder
# Secret for the RESTful API (optional)
# Authenticate by spedifying HTTP header `Authorization: Bearer ${secret}`
# ALWAYS set a secret if RESTful API is listening on 0.0.0.0
# secret: ""
# Outbound interface name
# interface-name: en0
# fwmark on Linux only
# routing-mark: 6666
# Static hosts for DNS server and connection establishment (like /etc/hosts)
#
# Wildcard hostnames are supported (e.g. *.clash.dev, *.foo.*.example.com)
# Non-wildcard domain names have a higher priority than wildcard domain names
# e.g. foo.example.com > *.example.com > .example.com
# P.S. +.foo.com equals to .foo.com and foo.com
# hosts:
# '*.clash.dev': 127.0.0.1
# '.dev': 127.0.0.1
# 'alpha.clash.dev': '::1'
# profile:
# Store the `select` results in $HOME/.config/clash/.cache
# set false If you don't want this behavior
# when two different configurations have groups with the same name, the selected values are shared
# store-selected: true
# persistence fakeip
# store-fake-ip: false
# DNS server settings
# This section is optional. When not present, the DNS server will be disabled.
dns:
enable: false
listen: 0.0.0.0:53
# ipv6: false # when the false, response to AAAA questions will be empty
# These nameservers are used to resolve the DNS nameserver hostnames below.
# Specify IP addresses only
default-nameserver:
- 114.114.114.114
- 8.8.8.8
# enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16 # Fake IP addresses pool CIDR
# use-hosts: true # lookup hosts and return IP record
# search-domains: [local] # search domains for A/AAAA record
# Hostnames in this list will not be resolved with fake IPs
# i.e. questions to these domain names will always be answered with their
# real IP addresses
# fake-ip-filter:
# - '*.lan'
# - localhost.ptlogin2.qq.com
# Supports UDP, TCP, DoT, DoH. You can specify the port to connect to.
# All DNS questions are sent directly to the nameserver, without proxies
# involved. Clash answers the DNS question with the first result gathered.
nameserver:
- 114.114.114.114 # default value
- 8.8.8.8 # default value
- tls://dns.rubyfish.cn:853 # DNS over TLS
- https://1.1.1.1/dns-query # DNS over HTTPS
- dhcp://en0 # dns from dhcp
# - '8.8.8.8#en0'
# When `fallback` is present, the DNS server will send concurrent requests
# to the servers in this section along with servers in `nameservers`.
# The answers from fallback servers are used when the GEOIP country
# is not `CN`.
# fallback:
# - tcp://1.1.1.1
# - 'tcp://1.1.1.1#en0'
# If IP addresses resolved with servers in `nameservers` are in the specified
# subnets below, they are considered invalid and results from `fallback`
# servers are used instead.
#
# IP address resolved with servers in `nameserver` is used when
# `fallback-filter.geoip` is true and when GEOIP of the IP address is `CN`.
#
# If `fallback-filter.geoip` is false, results from `nameserver` nameservers
# are always used if not match `fallback-filter.ipcidr`.
#
# This is a countermeasure against DNS pollution attacks.
# fallback-filter:
# geoip: true
# geoip-code: CN
# ipcidr:
# - 240.0.0.0/4
# domain:
# - '+.google.com'
# - '+.facebook.com'
# - '+.youtube.com'
# Lookup domains via specific nameservers
# nameserver-policy:
# 'www.baidu.com': '114.114.114.114'
# '+.internal.crop.com': '10.0.0.1'
proxies:
# Shadowsocks
# The supported ciphers (encryption methods):
# aes-128-gcm aes-192-gcm aes-256-gcm
# aes-128-cfb aes-192-cfb aes-256-cfb
# aes-128-ctr aes-192-ctr aes-256-ctr
# rc4-md5 chacha20-ietf xchacha20
# chacha20-ietf-poly1305 xchacha20-ietf-poly1305
- name: "ss1"
type: ss
server: server
port: 443
cipher: chacha20-ietf-poly1305
password: "password"
# udp: true
- name: "ss2"
type: ss
server: server
port: 443
cipher: chacha20-ietf-poly1305
password: "password"
plugin: obfs
plugin-opts:
mode: tls # or http
# host: bing.com
- name: "ss3"
type: ss
server: server
port: 443
cipher: chacha20-ietf-poly1305
password: "password"
plugin: v2ray-plugin
plugin-opts:
mode: websocket # no QUIC now
# tls: true # wss
# skip-cert-verify: true
# host: bing.com
# path: "/"
# mux: true
# headers:
# custom: value
# vmess
# cipher support auto/aes-128-gcm/chacha20-poly1305/none
- name: "vmess"
type: vmess
server: server
port: 443
uuid: uuid
alterId: 32
cipher: auto
# udp: true
# tls: true
# skip-cert-verify: true
# servername: example.com # priority over wss host
# network: ws
# ws-opts:
# path: /path
# headers:
# Host: v2ray.com
# max-early-data: 2048
# early-data-header-name: Sec-WebSocket-Protocol
- name: "vmess-h2"
type: vmess
server: server
port: 443
uuid: uuid
alterId: 32
cipher: auto
network: h2
tls: true
h2-opts:
host:
- http.example.com
- http-alt.example.com
path: /
- name: "vmess-http"
type: vmess
server: server
port: 443
uuid: uuid
alterId: 32
cipher: auto
# udp: true
# network: http
# http-opts:
# # method: "GET"
# # path:
# # - '/'
# # - '/video'
# # headers:
# # Connection:
# # - keep-alive
- name: vmess-grpc
server: server
port: 443
type: vmess
uuid: uuid
alterId: 32
cipher: auto
network: grpc
tls: true
servername: example.com
# skip-cert-verify: true
grpc-opts:
grpc-service-name: "example"
# socks5
- name: "socks"
type: socks5
server: server
port: 443
# username: username
# password: password
# tls: true
# skip-cert-verify: true
# udp: true
# http
- name: "http"
type: http
server: server
port: 443
# username: username
# password: password
# tls: true # https
# skip-cert-verify: true
# sni: custom.com
# Snell
# Beware that there's currently no UDP support yet
- name: "snell"
type: snell
server: server
port: 44046
psk: yourpsk
# version: 2
# obfs-opts:
# mode: http # or tls
# host: bing.com
# Trojan
- name: "trojan"
type: trojan
server: server
port: 443
password: yourpsk
# udp: true
# sni: example.com # aka server name
# alpn:
# - h2
# - http/1.1
# skip-cert-verify: true
- name: trojan-grpc
server: server
port: 443
type: trojan
password: "example"
network: grpc
sni: example.com
# skip-cert-verify: true
udp: true
grpc-opts:
grpc-service-name: "example"
- name: trojan-ws
server: server
port: 443
type: trojan
password: "example"
network: ws
sni: example.com
# skip-cert-verify: true
udp: true
# ws-opts:
# path: /path
# headers:
# Host: example.com
# ShadowsocksR
# The supported ciphers (encryption methods): all stream ciphers in ss
# The supported obfses:
# plain http_simple http_post
# random_head tls1.2_ticket_auth tls1.2_ticket_fastauth
# The supported supported protocols:
# origin auth_sha1_v4 auth_aes128_md5
# auth_aes128_sha1 auth_chain_a auth_chain_b
- name: "ssr"
type: ssr
server: server
port: 443
cipher: chacha20-ietf
password: "password"
obfs: tls1.2_ticket_auth
protocol: auth_sha1_v4
# obfs-param: domain.tld
# protocol-param: "#"
# udp: true
proxy-groups:
# relay chains the proxies. proxies shall not contain a relay. No UDP support.
# Traffic: clash <-> http <-> vmess <-> ss1 <-> ss2 <-> Internet
- name: "relay"
type: relay
proxies:
- http
- vmess
- ss1
- ss2
# url-test select which proxy will be used by benchmarking speed to a URL.
- name: "auto"
type: url-test
proxies:
- ss1
- ss2
- vmess1
# tolerance: 150
# lazy: true
url: 'http://www.gstatic.com/generate_204'
interval: 300
# fallback selects an available policy by priority. The availability is tested by accessing an URL, just like an auto url-test group.
- name: "fallback-auto"
type: fallback
proxies:
- ss1
- ss2
- vmess1
url: 'http://www.gstatic.com/generate_204'
interval: 300
# load-balance: The request of the same eTLD+1 will be dial to the same proxy.
- name: "load-balance"
type: load-balance
proxies:
- ss1
- ss2
- vmess1
url: 'http://www.gstatic.com/generate_204'
interval: 300
# strategy: consistent-hashing # or round-robin
# select is used for selecting proxy or proxy group
# you can use RESTful API to switch proxy is recommended for use in GUI.
- name: Proxy
type: select
# disable-udp: true
# filter: 'someregex'
proxies:
- ss1
- ss2
- vmess1
- auto
# direct to another interfacename or fwmark, also supported on proxy
- name: en1
type: select
interface-name: en1
routing-mark: 6667
proxies:
- DIRECT
- name: UseProvider
type: select
use:
- provider1
proxies:
- Proxy
- DIRECT
proxy-providers:
provider1:
type: http
url: "url"
interval: 3600
path: ./provider1.yaml
health-check:
enable: true
interval: 600
# lazy: true
url: http://www.gstatic.com/generate_204
test:
type: file
path: /test.yaml
health-check:
enable: true
interval: 36000
url: http://www.gstatic.com/generate_204
tunnels:
# one line config
- tcp/udp,127.0.0.1:6553,114.114.114.114:53,proxy
- tcp,127.0.0.1:6666,rds.mysql.com:3306,vpn
# full yaml config
- network: [tcp, udp]
address: 127.0.0.1:7777
target: target.com
proxy: proxy
rules:
- DOMAIN-SUFFIX,google.com,auto
- DOMAIN-KEYWORD,google,auto
- DOMAIN,google.com,auto
- DOMAIN-SUFFIX,ad.com,REJECT
- SRC-IP-CIDR,192.168.1.201/32,DIRECT
# optional param "no-resolve" for IP rules (GEOIP, IP-CIDR, IP-CIDR6)
- IP-CIDR,127.0.0.0/8,DIRECT
- GEOIP,CN,DIRECT
- DST-PORT,80,DIRECT
- SRC-PORT,7777,DIRECT
- RULE-SET,apple,REJECT # Premium only
- MATCH,auto
```

72
docs/configuration/dns.md Normal file
View File

@ -0,0 +1,72 @@
---
sidebarTitle: Clash DNS
sidebarOrder: 6
---
# Clash DNS
Since some parts of Clash run on the Layer 3 (Network Layer), they would've been impossible to obtain domain names of the packets for rule-based routing.
*Enter fake-ip*. It enables rule-based routing, minimises the impact of DNS pollution attack and improves network performance, sometimes drastically.
## fake-ip
The concept of "fake IP" addresses is originated from [RFC 3089](https://tools.ietf.org/rfc/rfc3089):
> A "fake IP" address is used as a key to look up the corresponding "FQDN" information.
The default CIDR for the fake-ip pool is `198.18.0.1/16`, a reserved IPv4 address space, which can be changed in `dns.fake-ip-range`.
When a DNS request is sent to the Clash DNS, the core allocates a *free* fake-ip address from the pool, by managing an internal mapping of domain names and their fake-ip addresses.
Take an example of accessing `http://google.com` with your browser.
1. The browser asks Clash DNS for the IP address of `google.com`
2. Clash checks the internal mapping and returned `198.18.1.5`
3. The browser sends an HTTP request to `198.18.1.5` on `80/tcp`
4. When receiving the inbound packet for `198.18.1.5`, Clash looks up the internal mapping and realises the client is actually sending a packet to `google.com`
5. Depending on the rules:
1. Clash may just send the domain name to an outbound proxy like SOCKS5 or shadowsocks and establish the connection with the proxy server
2. or Clash might look for the real IP address of `google.com`, in the case of encountering a `SCRIPT`, `GEOIP`, `IP-CIDR` rule, or the case of DIRECT outbound
Being a confusing concept, I'll take another example of accessing `http://google.com` with the cURL utility:
```txt{2,3,5,6,8,9}
$ curl -v http://google.com
<---- cURL asks your system DNS (Clash) about the IP address of google.com
----> Clash decided 198.18.1.70 should be used as google.com and remembers it
* Trying 198.18.1.70:80...
<---- cURL connects to 198.18.1.70 tcp/80
----> Clash will accept the connection immediately, and..
* Connected to google.com (198.18.1.70) port 80 (#0)
----> Clash looks up in its memory and found 198.18.1.70 being google.com
----> Clash looks up in the rules and sends the packet via the matching outbound
> GET / HTTP/1.1
> Host: google.com
> User-Agent: curl/8.0.1
> Accept: */*
>
< HTTP/1.1 301 Moved Permanently
< Location: http://www.google.com/
< Content-Type: text/html; charset=UTF-8
< Content-Security-Policy-Report-Only: object-src 'none';base-uri 'self';script-src 'nonce-ahELFt78xOoxhySY2lQ34A' 'strict-dynamic' 'report-sample' 'unsafe-eval' 'unsafe-inline' https: http:;report-uri https://csp.withgoogle.com/csp/gws/other-hp
< Date: Thu, 11 May 2023 06:52:19 GMT
< Expires: Sat, 10 Jun 2023 06:52:19 GMT
< Cache-Control: public, max-age=2592000
< Server: gws
< Content-Length: 219
< X-XSS-Protection: 0
< X-Frame-Options: SAMEORIGIN
<
<HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8">
<TITLE>301 Moved</TITLE></HEAD><BODY>
<H1>301 Moved</H1>
The document has moved
<A HREF="http://www.google.com/">here</A>.
</BODY></HTML>
* Connection #0 to host google.com left intact
```
<!-- TODO: nameserver, fallback, fallback-filter, hosts, search-domains, fake-ip-filter, nameserver-policy -->

64
docs/configuration/getting-started.md Normal file
View File

@ -0,0 +1,64 @@
---
sidebarTitle: Getting Started
sidebarOrder: 2
---
# Getting Started
It's recommended that you read the [Introduction](/configuration/introduction) before proceeding. After you have a brief understanding of how Clash works, you can start writing your own configuration.
## Configuration Files
The main configuration file is called `config.yaml`. By default, Clash reads the configuration files at `$HOME/.config/clash`. If it doesn't exist, Clash will generate a minimal configuration file at that location.
If you want to place your configurations elsewhere (e.g. `/etc/clash`), you can use command-line option `-d` to specify a configuration directory:
```shell
clash -d . # current directory
clash -d /etc/clash
```
Or, you can use option `-f` to specify a configuration file:
```shell
clash -f ./config.yaml
clash -f /etc/clash/config.yaml
```
## Special Syntaxes
There are some special syntaxes in Clash configuration files, of which you might want to be aware:
### IPv6 Addresses
You should wrap IPv6 addresses in square brackets, for example:
```txt
[aaaa::a8aa:ff:fe09:57d8]
```
### DNS Wildcard Domain Matching
In some cases, you will need to match against wildcard domains. For example, when you're setting up [Clash DNS](/configuration/dns), you might want to match against all subdomains of `localdomain`.
Clash do offer support on matching different levels of wildcard domains in the DNS configuration, while the syntaxes defined below:
::: tip
Any domain with these characters should be wrapped with single quotes (`'`). For example, `'*.google.com'`.
:::
Use an astrisk (`*`) to match against a single-level wildcard subdomain.
| Expression | Matches | Does Not Match |
| ---------- | ------- | -------------- |
| `*.google.com` | `www.google.com` | `google.com` |
| `*.bar.google.com` | `foo.bar.google.com` | `bar.google.com` |
| `*.*.google.com` | `thoughtful.sandbox.google.com` | `one.two.three.google.com` |
Use a plus sign (`+`) to match against multi-level wildcard subdomains.
| Expression | Matches | Does Not Match |
| ---------- | ------- | -------------- |
| `+.google.com` | `www.google.com` | `www.google.com` |
| `+.google.com` | `thoughtful.sandbox.google.com` | `www.google.com` |
| `+.google.com` | `one.two.three.google.com` | `www.google.com` |

69
docs/configuration/inbound.md Normal file
View File

@ -0,0 +1,69 @@
---
sidebarTitle: Inbound
sidebarOrder: 3
---
# Inbound
Clash supports multiple inbound protocols, including:
- SOCKS5
- HTTP(S)
- Redirect TCP
- TProxy TCP
- TProxy UDP
- Linux TUN device (Premium only)
Connections to any inbound protocol listed above will be handled by the same internal rule-matching engine. That is to say, Clash does not (currently) support different rule sets for different inbounds.
## Configuration
```yaml
# Port of HTTP(S) proxy server on the local end
# port: 7890
# Port of SOCKS5 proxy server on the local end
# socks-port: 7891
# HTTP(S) and SOCKS4(A)/SOCKS5 server on the same port
mixed-port: 7890
# Transparent proxy server port for Linux and macOS (Redirect TCP and TProxy UDP)
# redir-port: 7892
# Transparent proxy server port for Linux (TProxy TCP and TProxy UDP)
# tproxy-port: 7893
# Allow clients other than 127.0.0.1 to connect to the inbounds
allow-lan: false
```
## The Mixed Port
The mixed port is a special port that supports both HTTP(S) and SOCKS5 protocols. You can have any programs that support either HTTP or SOCKS proxy to connect to this port, for example:
```shell
$ curl -x socks5h://127.0.0.1:7890 -v http://connect.rom.miui.com/generate_204
* Trying 127.0.0.1:7890...
* SOCKS5 connect to connect.rom.miui.com:80 (remotely resolved)
* SOCKS5 request granted.
* Connected to (nil) (127.0.0.1) port 7890 (#0)
> GET /generate_204 HTTP/1.1
> Host: connect.rom.miui.com
> User-Agent: curl/7.81.0
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 204 No Content
< Date: Thu, 11 May 2023 06:18:22 GMT
< Connection: keep-alive
< Content-Type: text/plain
<
* Connection #0 to host (nil) left intact
```
## Redirect and TProxy
Redirect and TProxy are two different ways of implementing transparent proxying. They are both supported by Clash.
However, you most likely don't need to mess with these two inbounds - we recommend using [Clash Premium](/premium/introduction) if you want to use transparent proxying, as it has built-in support of the automatic management of the route table, rules and nftables.

38
docs/configuration/introduction.md Normal file
View File

@ -0,0 +1,38 @@
---
sidebarTitle: Introduction
sidebarOrder: 1
---
# Introduction
In this chapter, we'll cover the common features of Clash and how they should be used and configured.
Clash uses [YAML](https://yaml.org), _YAML Ain't Markup Language_, for configuration files. YAML is designed to be easy to be read, be written, and be interpreted by computers, and is commonly used for exact configuration files.
## Understanding how Clash works
Before proceeding, it's important to understand how Clash works, in which there are two critical components:
![](/assets/connection-flow.png)
<!-- https://excalidraw.com/clash-connection-flow#json=OHsOdaqAUPuuN7VPvdZ9Z,NT7rRrtzRgbVIM0tpkPnGA -->
### Inbound
Inbound is the component that listens on the local end. It works by opening a local port and listening for incoming connections. When a connection comes in, Clash looks up the rules that are configured in the configuration file, and decides which outbound that the connection should go next.
### Outbound
Outbound is the component that connects to the remote end. Depending on the configuration, it can be a specific network interface, a proxy server, or a [proxy group](#proxy-groups).
## Rule-based Routing
Clash supports rule-based routing, which means you can route packets to different outbounds based on the a variety of contraints. The rules can be defined in the `rules` section of the configuration file.
There's a number of available rule types, and each rule type has its own syntax. The general syntax of a rule is:
```txt
TYPE,ARGUMENT,POLICY(,no-resolve)
```
In the upcoming guides, you will learn more about how rules can be configured.

432
docs/configuration/outbound.md Normal file
View File

@ -0,0 +1,432 @@
---
sidebarTitle: Outbound
sidebarOrder: 4
---
# Outbound
There are several types of outbound targets in Clash. Each type has its own features and usage scenarios. In this page, we'll cover the common features of each type and how they should be used and configured.
[[toc]]
## Proxies
Proxies are the basic type of outbound targets.
### Shadowsocks
Clash supports the following ciphers (encryption methods) for Shadowsocks:
| Family | Ciphers |
| ------ | ------- |
| AEAD | aes-128-gcm, aes-192-gcm, aes-256-gcm, chacha20-ietf-poly1305, xchacha20-ietf-poly1305 |
| Stream | aes-128-cfb, aes-192-cfb, aes-256-cfb, rc4-md5, chacha20-ietf, xchacha20 |
| Block | aes-128-ctr, aes-192-ctr, aes-256-ctr |
In addition, Clash also supports popular Shadsocks plugins `obfs` and `v2ray-plugin`.
::: code-group
```yaml [basic]
- name: "ss1"
type: ss
# interface-name: eth0
# routing-mark: 1234
server: server
port: 443
cipher: chacha20-ietf-poly1305
password: "password"
# udp: true
```
```yaml [obfs]
- name: "ss2"
type: ss
# interface-name: eth0
# routing-mark: 1234
server: server
port: 443
cipher: chacha20-ietf-poly1305
password: "password"
plugin: obfs
plugin-opts:
mode: tls # or http
# host: bing.com
```
```yaml [ws (websocket)]
- name: "ss3"
type: ss
# interface-name: eth0
# routing-mark: 1234
server: server
port: 443
cipher: chacha20-ietf-poly1305
password: "password"
plugin: v2ray-plugin
plugin-opts:
mode: websocket # no QUIC now
# tls: true # wss
# skip-cert-verify: true
# host: bing.com
# path: "/"
# mux: true
# headers:
# custom: value
```
:::
### ShadowsocksR
Clash supports the infamous anti-censorship protocol ShadowsocksR as well. The supported ciphers:
| Family | Ciphers |
| ------ | ------- |
| Stream | aes-128-cfb, aes-192-cfb, aes-256-cfb, rc4-md5, chacha20-ietf, xchacha20 |
Supported obfuscation methods:
- plain
- http_simple
- http_post
- random_head
- tls1.2_ticket_auth
- tls1.2_ticket_fastauth
Supported protocols:
- origin
- auth_sha1_v4
- auth_aes128_md5
- auth_aes128_sha1
- auth_chain_a auth_chain_b
```yaml
- name: "ssr"
type: ssr
# interface-name: eth0
# routing-mark: 1234
server: server
port: 443
cipher: chacha20-ietf
password: "password"
obfs: tls1.2_ticket_auth
protocol: auth_sha1_v4
# obfs-param: domain.tld
# protocol-param: "#"
# udp: true
```
### Vmess
Clash supports the following ciphers (encryption methods) for Vmess:
- auto
- aes-128-gcm
- chacha20-poly1305
- none
::: code-group
```yaml [basic]
- name: "vmess"
type: vmess
# interface-name: eth0
# routing-mark: 1234
server: server
port: 443
uuid: uuid
alterId: 32
cipher: auto
# udp: true
# tls: true
# skip-cert-verify: true
# servername: example.com # priority over wss host
# network: ws
# ws-opts:
# path: /path
# headers:
# Host: v2ray.com
# max-early-data: 2048
# early-data-header-name: Sec-WebSocket-Protocol
```
```yaml [HTTP]
- name: "vmess-http"
type: vmess
# interface-name: eth0
# routing-mark: 1234
server: server
port: 443
uuid: uuid
alterId: 32
cipher: auto
# udp: true
# network: http
# http-opts:
# # method: "GET"
# # path:
# # - '/'
# # - '/video'
# # headers:
# # Connection:
# # - keep-alive
```
```yaml [HTTP/2]
- name: "vmess-h2"
type: vmess
# interface-name: eth0
# routing-mark: 1234
server: server
port: 443
uuid: uuid
alterId: 32
cipher: auto
network: h2
tls: true
h2-opts:
host:
- http.example.com
- http-alt.example.com
path: /
```
```yaml [gRPC]
- name: vmess-grpc
type: vmess
# interface-name: eth0
# routing-mark: 1234
server: server
port: 443
uuid: uuid
alterId: 32
cipher: auto
network: grpc
tls: true
servername: example.com
# skip-cert-verify: true
grpc-opts:
grpc-service-name: "example"
```
:::
### SOCKS5
In addition, Clash supports SOCKS5 outbound as well:
```yaml
- name: "socks"
type: socks5
# interface-name: eth0
# routing-mark: 1234
server: server
port: 443
# username: username
# password: password
# tls: true
# skip-cert-verify: true
# udp: true
```
### HTTP
Clash also supports HTTP outbound:
::: code-group
```yaml [HTTP]
- name: "http"
type: http
# interface-name: eth0
# routing-mark: 1234
server: server
port: 443
# username: username
# password: password
```
```yaml [HTTPS]
- name: "http"
type: http
# interface-name: eth0
# routing-mark: 1234
server: server
port: 443
tls: true
# skip-cert-verify: true
# sni: custom.com
# username: username
# password: password
```
:::
### Snell
Being an alternative protocol for anti-censorship, Clash has integrated support for Snell as well.
```yaml
# No UDP support yet
- name: "snell"
type: snell
# interface-name: eth0
# routing-mark: 1234
server: server
port: 44046
psk: yourpsk
# version: 2
# obfs-opts:
# mode: http # or tls
# host: bing.com
```
### Trojan
Clash has built support for the popular protocol Trojan:
::: code-group
```yaml [basic]
- name: "trojan"
type: trojan
# interface-name: eth0
# routing-mark: 1234
server: server
port: 443
password: yourpsk
# udp: true
# sni: example.com # aka server name
# alpn:
# - h2
# - http/1.1
# skip-cert-verify: true
```
```yaml [gRPC]
- name: trojan-grpc
type: trojan
# interface-name: eth0
# routing-mark: 1234
server: server
port: 443
password: "example"
network: grpc
sni: example.com
# skip-cert-verify: true
udp: true
grpc-opts:
grpc-service-name: "example"
```
```yaml [ws (websocket)]
- name: trojan-ws
type: trojan
# interface-name: eth0
# routing-mark: 1234
server: server
port: 443
password: "example"
network: ws
sni: example.com
# skip-cert-verify: true
udp: true
# ws-opts:
# path: /path
# headers:
# Host: example.com
```
:::
## Proxy Groups
Proxy Groups are groups of proxies that you can use directly as a rule policy.
### relay
The request sent to this proxy group will be relayed through the specified proxy servers sequently. There's currently no UDP support on this. The specified proxy servers should not contain another relay.
### url-test
Clash benchmarks each proxy servers in the list, by sending HTTP HEAD requests to a specified URL through these servers periodically. It's possible to set a maximum tolerance value, benchmarking interval, and the target URL.
### fallback
Clash periodically tests the availability of servers in the list with the same mechanism of `url-test`. The first available server will be used.
### load-balance
The request to the same eTLD+1 will be dialed with the same proxy.
### select
The first server is by default used when Clash starts up. Users can choose the server to use with the RESTful API. In this mode, you can hardcode servers in the config or use [Proxy Providers](/configuration/outbound#proxy-providers).
Either way, sometimes you might as well just route packets with a direct connection. In this case, you can use the `DIRECT` outbound.
To use a different network interface, you will need to use a Proxy Group that contains a `DIRECT` outbound with the `interface-name` option set.
```yaml
- name: "My Wireguard Outbound"
type: select
interface-name: wg0
proxies: [ 'DIRECT' ]
```
## Proxy Providers
Proxy Providers give users the power to load proxy server lists dynamically, instead of hardcoding them in the configuration file. There are currently two sources for a proxy provider to load server list from:
- `http`: Clash loads the server list from a specified URL on startup. Clash periodically pulls the server list from remote if the `interval` option is set.
- `file`: Clash loads the server list from a specified location on the filesystem on startup.
Health check is available for both modes, and works exactly like `fallback` in Proxy Groups. The configuration format for the server list files is also exactly the same in the main configuration file:
::: code-group
```yaml [config.yaml]
proxy-providers:
provider1:
type: http
url: "url"
interval: 3600
path: ./provider1.yaml
# filter: 'a|b' # golang regex string
health-check:
enable: true
interval: 600
# lazy: true
url: http://www.gstatic.com/generate_204
test:
type: file
path: /test.yaml
health-check:
enable: true
interval: 36000
url: http://www.gstatic.com/generate_204
```
```yaml [test.yaml]
proxies:
- name: "ss1"
type: ss
server: server
port: 443
cipher: chacha20-ietf-poly1305
password: "password"
- name: "ss2"
type: ss
server: server
port: 443
cipher: chacha20-ietf-poly1305
password: "password"
plugin: obfs
plugin-opts:
mode: tls
```
:::

153
docs/configuration/rules.md Normal file
View File

@ -0,0 +1,153 @@
---
sidebarTitle: Rules
sidebarOrder: 5
---
# Rules
In the Getting Started guide, we covered the basics of rule-based matching in Clash. In this chapter, we'll cover all available rule types in the latest version of Clash.
```txt
TYPE,ARGUMENT,POLICY(,no-resolve)
```
The `no-resolve` option is optional, and it's used to skip DNS resolution for the rule. It's useful when you want to use `GEOIP`, `IP-CIDR`, `IP-CIDR6`, `SCRIPT` rules, but don't want to resolve the domain name to an IP address just yet.
[[toc]]
## Policy
There are four types of POLICY for now, in which:
- DIRECT: directly connects to the target through `interface-name` (does not lookup system route table)
- REJECT: drops the packet
- Proxy: routes the packet to the specified proxy server
- Proxy Group: routes the packet to the specified proxy group
## Types of rules
There are a number of rules where one might find useful. The following section covers each rule type and how they should be used.
### DOMAIN
`DOMAIN,www.google.com,policy` routes only `www.google.com` to `policy`.
### DOMAIN-SUFFIX
`DOMAIN-SUFFIX,youtube.com,policy` routes any domain names that ends with `youtube.com`.
In this case, `www.youtube.com` and `foo.bar.youtube.com` will be routed to `policy`.
### DOMAIN-KEYWORD
`DOMAIN-KEYWORD,google,policy` routes any domain names to policy that contains `google`.
In this case, `www.google.com` or `googleapis.com` are routed to `policy`.
### GEOIP
GEOIP rules are used to route packets based on the **country code** of the target IP address. Clash uses [MaxMind GeoLite2](https://dev.maxmind.com/geoip/geoip2/geolite2/) database for this feature.
::: warning
When encountering this rule, Clash will resolve the domain name to an IP address and then look up the country code of the IP address. If you want to skip the DNS resolution, use `no-resolve` option.
:::
`GEOIP,CN,policy` routes any packets destined to a China IP address to `policy`.
### IP-CIDR
IP-CIDR rules are used to route packets based on the **destination IPv4 address** of the packet.
::: warning
When encountering this rule, Clash will resolve the domain name to an IP address and then look up the country code of the IP address. If you want to skip the DNS resolution, use `no-resolve` option.
:::
`IP-CIDR,127.0.0.0/8,DIRECT` routes any packets destined to `127.0.0.0/8` to the `DIRECT` outbound.
### IP-CIDR6
IP-CIDR6 rules are used to route packets based on the **destination IPv6 address** of the packet.
::: warning
When encountering this rule, Clash will resolve the domain name to an IP address and then look up the country code of the IP address. If you want to skip the DNS resolution, use `no-resolve` option.
:::
`IP-CIDR6,2620:0:2d0:200::7/32,policy` routes any packets destined to `2620:0:2d0:200::7/32` to `policy`.
### SRC-IP-CIDR
SRC-IP-CIDR rules are used to route packets based on the **source IPv4 address** of the packet.
`SRC-IP-CIDR,192.168.1.201/32,DIRECT` routes any packets **from** `192.168.1.201/32` to the `DIRECT` policy.
### SRC-PORT
SRC-PORT rules are used to route packets based on the **source port** of the packet.
`SRC-PORT,80,policy` routes any packets **from** the port 80 to `policy`.
### DST-PORT
DST-PORT rules are used to route packets based on the **destination port** of the packet.
`DST-PORT,80,policy` routes any packets **to** the port 80 to `policy`.
### PROCESS-NAME
PROCESS-NAME rules are used to route packets based on the name of process that is sending the packet.
::: warning
Currently, only macOS, Linux, FreeBSD and Windows are supported.
:::
`PROCESS-NAME,nc,DIRECT` routes all packets from the process `nc` to the `DIRECT` outbound.
### PROCESS-PATH
PROCESS-PATH rules are used to route packets based on the PATH of process that is sending the packet.
::: warning
Currently, only macOS, Linux, FreeBSD and Windows are supported.
:::
`PROCESS-PATH,/bin/sh,DIRECT` routes all packets from the process `/bin/sh` to the `DIRECT` outbound.
### IPSET
IPSET rules are used to match against an IP set and route packets based on the result. According to the [official website of IPSET](https://ipset.netfilter.org/):
> IP sets are a framework inside the Linux kernel, which can be administered by the ipset utility. Depending on the type, an IP set may store IP addresses, networks, (TCP/UDP) port numbers, MAC addresses, interface names or combinations of them in a way, which ensures lightning speed when matching an entry against a set.
::: warning
This feature only works on Linux and requires `ipset` to be installed.
:::
`PROCESS-PATH,/bin/sh,DIRECT` routes all packets from the process `/bin/sh` to the `DIRECT` outbound.
### RULE-SET
::: info
This feature is only available in the [Premium](/premium/introduction) edtion.
:::
RULE-SET rules are used to route packets based on the result of a [rule provider](/premium/rule-providers). When Clash encounters this rule, it loads the rules from the specified rule provider and then matches the packet against the rules. If the packet matches any of the rules, the packet will be routed to the specified policy, otherwise the rule is skipped.
`RULE-SET,my-rule-provider,DIRECT` loads all rules from `my-rule-provider` and sends the matched packets to the `DIRECT` outbound.
### SCRIPT
::: info
This feature is only available in the [Premium](/premium/introduction) edtion.
:::
SCRIPT rules are special rules that are used to route packets based on the result of a [script shortcut](/premium/script-shortcuts). When Clash encounters this rule, it evaluates the expression. If it returns `true`, the packet will be routed to the specified policy, otherwise the rule is skipped.
::: warning
When encountering this rule, Clash will resolve the domain name to an IP address and then look up the country code of the IP address. If you want to skip the DNS resolution, use `no-resolve` option.
:::
`SCRIPT,SHORTCUT-NAME,policy` routes any packets to `policy` if they have the shortcut evaluated `true`.
### MATCH
`MATCH,policy` routes the rest of the packets to `policy`. This rule is **required**.