DOCSEARCHbyAlgolia
Submit Docs

leaf

repository·master·Indexed 25 days ago

https://github.com/eycorsican/leaf

A versatile and efficient proxy framework supporting various protocols (HTTP, SOCKS5, Shadowsocks, Trojan, VMess, Vless), transports (WebSocket, TLS, QUIC, AMux, Obfs, Reality, MPTP), and traffic control mechanisms like chaining and failover. It includes a CLI for proxy management and an FFI for integration, featuring a Multipath Transport Protocol (MPTP) for bandwidth aggregation and connection resilience.

Tokens
10.7K
Snippets
38
Records
103
Agent score
81%

What's inside leaf

  1. Overview of Leaf supported protocols and features

    master

    Leaf is a versatile proxy framework supporting various protocols, transports, and traffic control mechanisms.

    Proxy Protocols

    • HTTP: Inbound only
    • SOCKS5: Inbound and Outbound
    • Shadowsocks: Inbound and Outbound
    • Trojan: Inbound and Outbound
    • VMess: Outbound only
    • Vless: Outbound only

    Transports & Security

    • WebSocket, TLS, QUIC: Inbound and Outbound
    • AMux: Leaf-specific multiplexing (Inbound and Outbound)
    • Obfs: Simple obfuscation (Outbound only)
    • Reality: Xray Reality (Outbound only)
    • MPTP: Multi-path Transport Protocol for aggregation (Inbound and Outbound)

    Traffic Control

    • Chain: Proxy chaining (Inbound and Outbound)
    • Failover: Failover with health check (Outbound only)

    Transparent Proxying

    • TUN: Inbound only (Supported on Linux, macOS, Windows, iOS, Android via lwip/smoltcp)
    • NF: Inbound only (Windows via NetFilter SDK)
    • TPROXY: Not yet supported (Linux)

  2. Understand MPTP Architecture

    master

    MPTP (Multipath Transport Protocol) is designed to aggregate multiple reliable connections into a single logical tunnel. This provides two primary benefits:

    1. Bandwidth Aggregation: Combining the throughput of multiple paths (e.g., different relays or direct connections).
    2. Connection Resilience: Maintaining a stable logical connection even if individual sub-connections (paths) fail.

    The system consists of an MPTP Client (which acts as a SOCKS5 listener) and an MPTP Server (which connects to the final target). Data is split into frames at the client, distributed across multiple paths (Relays or Direct), and reassembled at the server.

  4. Build and run Leaf with MPTP

    master

    To use MPTP, build the leaf-cli package and run the binary with your specific configuration files.

    Build:

    cargo build -p leaf-cli --release

    Run Server:

    ./target/release/leaf -c server.json

    Run Client:

    ./target/release/leaf -c client.json
    cargo build -p leaf-cli --release
./target/release/leaf -c server.json
./target/release/leaf -c client.json

  5. Deploy MPTP (Multipath Transport Protocol)

    master

    MPTP combines multiple outbound paths into a single logical transport channel. A typical deployment involves:

    • Client side: A local socks inbound connected to an mptp outbound.
    • Server side: An mptp inbound connected to a direct outbound.

    To achieve multipath aggregation, ensure the actors list contains at least two outbound tags.

  6. MPTP Connection Establishment and Data Flow

    master

    The MPTP connection process follows a specific sequence of phases:

    1. SOCKS5 Handshake

    The user application (e.g., Browser, Curl) initiates a standard SOCKS5 handshake with the MPTP Client. The client supports No Auth.

    2. MPTP Session Establishment

    Once the SOCKS5 request is received, the MPTP Client:

    • Generates a unique CID (Connection ID) using a UUID.
    • Establishes multiple sub-connections (multipath) via various routes (e.g., Relay A, Relay B, or a Direct connection).
    • Performs a handshake on each path with the MPTP Server using the format: [VER, CID, CMD, DST_ADDR, DST_PORT].

    The MPTP Server uses the CID to match incoming packets to the correct session.

    3. Data Tunneling

    • Client Side: Raw TCP bytes or UDP packets are encapsulated into frames (Len+Data) and scheduled across available sub-connections.
    • Server Side: Frames are reassembled and forwarded to the target server via TCP or UDP. Return traffic follows the reverse process.

  8. Configure MPTP via JSON

    master

    To use MPTP in a JSON configuration, set the outbound protocol to mptp and define the settings. To act as an MPTP server, set the inbound protocol to mptp.

    Key Fields:

    • outbounds[].protocol: Set to "mptp" to enable the MPTP client outbound.
    • settings.actors: A list of outbound tags used as sub-connections.
    • settings.address: The MPTP server address.
    • settings.port: The MPTP server port.
    • inbounds[].protocol: Set to "mptp" to enable the MPTP server inbound listener.
    // Client example (client.json)
{
  "inbounds": [
    {
      "protocol": "socks",
      "address": "127.0.0.1",
      "port": 1086
    }
  ],
  "outbounds": [
    {
      "protocol": "mptp",
      "settings": {
        "actors": [
          "direct1",
          "direct2"
        ],
        "address": "127.0.0.1",
        "port": 3001
      }
    },
    {
      "protocol": "direct",
      "tag": "direct1"
    },
    {
      "protocol": "direct",
      "tag": "direct2"
    }
  ]
}

// Server example (server.json)
{
  "inbounds": [
    {
      "protocol": "mptp",
      "address": "0.0.0.0",
      "port": 3001
    }
  ],
  "outbounds": [
    {
      "protocol": "direct"
    }
  ]
}

  9. Validate MPTP configuration

    master

    Before deploying to production, verify your configuration syntax and connectivity.

    1. Verify configuration syntax: Use the -T flag to test the configuration without starting the service.

    ./target/release/leaf -c client.json -T
./target/release/leaf -c server.json -T

    2. Test connectivity via SOCKS5: If your client is configured with a local SOCKS5 proxy at 127.0.0.1:1086, test it using curl:

    curl --socks5 127.0.0.1:1086 https://example.com
    ./target/release/leaf -c client.json -T
curl --socks5 127.0.0.1:1086 https://example.com

  10. Configure the Shadowsocks plugin via arguments

    master

    The Shadowsocks plugin is registered via a plugin_spec and initialized using the add_handler_fn. When providing arguments to the plugin, they must be a semicolon-separated string in the following order:

    1. address: The server IP or domain.
    2. port: The server port (as a u16).
    3. cipher: The encryption cipher to use.
    4. password: The encryption password.

    Example argument string: 127.0.0.1;8388;aes-256-gcm;password123