DOCSEARCHbyAlgolia
Submit Docs

clash-rs

repository·master·Indexed 23 days ago

https://github.com/watfaq/clash-rs

A custom, rule-based network proxy software designed for flexible traffic routing. It supports a wide array of inbound and outbound protocols (including Shadowsocks, Trojan, VLESS, and WireGuard), local anti-spoofing DNS, and Jaeger tracing. The project includes a web-based dashboard for managing configurations, proxy groups, and monitoring network flows via a WebSocket API. It is cross-platform, supporting Linux, macOS, Windows, and iOS.

Tokens
15.3K
Snippets
28
Records
83
Agent score
82%

What's inside clash-rs

  1. Environment Support and Windows Requirements

    master

    ClashRS supports Linux, macOS, Windows, and iOS.

    Windows Note: To use TUN/transparent proxying on Windows, you must copy the wintun.dll file (matching your architecture) into the same directory as the ClashRS executable and run the program with Administrator privileges.

  2. Embed the dashboard in the clash-rs binary

    master

    The dashboard can be served directly by the clash-rs binary. To enable this:

    1. Enable the builtin-dashboard feature flag in clash-rs during compilation.
    2. The built dist/ folder from the dashboard project is embedded into the binary at compile time.
    3. Once embedded, the dashboard is served under the /ui/ path prefix.

    The dashboard is configured with base: './' in Vite to ensure it can be served correctly from any path prefix.

  3. Compare performance of netstack implementations

    master

    The watfaq-netstack package provides different network stack implementations that can be benchmarked using iperf3.

    • with_tun_rs: A baseline TUN implementation.
    • netstack-lwip: An implementation using lwIP.
    • netstack-smoltcp: An implementation using smoltcp. Note that for smoltcp, the socket buffer size is a critical factor for achieving maximum throughput.

  4. Develop the Clash RS Dashboard locally

    master

    To start a local development environment for the dashboard, install dependencies and run the development server using npm.

    By default, the dashboard attempts to connect to the clash-rs API at the current origin (window.location.origin). To connect to a local clash-rs instance running on a different port or address:

    1. Open the Settings page in the dashboard.
    2. Set the API URL to your clash-rs address (e.g., http://localhost:9090).
    3. Set the secret if your clash-rs instance is configured with one.

    Alternatively, you can set the clash-api-url key in localStorage before loading the page.

    npm install
npm run dev

  5. Profile watfaq-netstack performance with flamegraph

    master
    To profile the performance of the watfaq-netstack package using cargo flamegraph, you can run the specific examples for different network stack implementations. This is useful for identifying bottlenecks in the Device implementation, such as memory allocations or packet processing overhead.

  7. Install ClashRS via prebuilt binaries, Docker, or local build

    master

    You can install ClashRS using several methods depending on your environment:

    Download Prebuilt Binaries

    Download the latest releases from the official GitHub releases page.

    Docker Image

    Use the official container image available on GitHub Container Registry: ghcr.io/watfaq/clash-rs (link: https://github.com/watfaq/clash-rs/pkgs/container/clash-rs)

    Local Build

    To build from source, ensure you have the following dependencies installed:

    • cmake (3.29 or newer)
    • libclang (LLVM)
    • nasm (Required for Windows)
    • protoc (For geodata proto generation)
    • pre-commit (For managing git hooks)
    # Install and setup git hooks
pipx install pre-commit
pre-commit install

# Build the project
cargo build
    $ pipx install pre-commit
$ pre-commit install

$ cargo build

  10. Run ClashRS with a configuration file

    master

    To run ClashRS, you need a configuration file (e.g., sample.yaml). Use the -c or --config flag to specify the path to your configuration file. By default, it looks for config.yaml in the current directory.

    Example configuration (sample.yaml):

    port: 7890

    Run the executable:

    ./target/debug/clash-rs -c sample.yaml

  11. How composite rules and boolean operators work

    master

    CompositeRule allows for complex traffic routing logic by combining multiple individual rules using boolean operators. It supports nested expressions, enabling highly granular control over how network sessions are matched to specific proxy targets.

    Supported Operators

    • AND: All sub-expressions must evaluate to true for the composite rule to match.
    • OR: At least one sub-expression must evaluate to true for the composite rule to match.
    • NOT: Inverts the result of the single sub-expression provided. Note that NOT requires exactly one sub-expression.

    Expression Syntax

    Expressions must be wrapped in parentheses. Sub-expressions are also wrapped in parentheses and separated by commas.

    Example: AND with nested OR To match a specific domain where the network is either UDP or TCP: ((DOMAIN,example.com),(OR,((NETWORK,UDP),(NETWORK,TCP))))

    Example: OR with multiple domains ((DOMAIN,a.com),(DOMAIN,b.com),(DOMAIN,c.com))

    Example: NOT operator To match everything except a specific domain: ((DOMAIN,baidu.com))

  12. How Reality TLS and XTLS-Vision splice mode work together

    master

    The Client implementation supports both standard Reality TLS and a specialized "spliced" mode used by XTLS-Vision.

    Standard Mode

    Using proxy_stream establishes a standard Reality TLS connection over an AnyStream.

    Splice Mode (XTLS-Vision)

    When using proxy_stream_spliced, the client establishes a connection that can transition from encrypted TLS to raw TCP (splice mode) without re-handshaking. This is achieved through a layer stack involving VisionStream, VlessStream, and SplicableTlsStream.

    The Splice Sequence:

    1. Reality TLS Handshake: Initial connection is fully encrypted.
    2. Vision Framing: The client sends VLESS-framed inner TLS traffic.
    3. Trigger: When the server sends CMD_PADDING_DIRECT (0x02), the VisionStream sets read_flag and write_flag in the VisionOptions to true.
    4. Splice: The SplicableTlsStream detects these flags and bypasses the TLS encryption layer, allowing raw bytes to flow directly on the underlying TCP socket.

    This mechanism allows for high-performance data transfer by removing the overhead of outer TLS encryption once the inner TLS handshake is complete.

    /* 
Layer stack:
 VisionStream          (owns VisionOptions – writes the flags)
   └─ VlessStream      (VLESS framing)
       └─ SplicableTlsStream  (reads the flags; bypasses TLS when set)
           └─ Reality TLS
               └─ TCP
*/