DOCSEARCHbyAlgolia
Submit Docs

Meridian Documentation

repository·main·Indexed 19 days ago

https://github.com/getmeridian/meridian

An orchestrator for deploying undetectable, hardened proxy servers using the VLESS+Reality protocol. Meridian automates the configuration of Docker, Xray, nginx, firewalls, and TLS certificates to make proxy servers indistinguishable from legitimate websites. It includes tools for managing clients via QR codes, deploying relay nodes using Realm, and performing pre-flight server validations to avoid detection.

Tokens
37.5K
Snippets
128
Records
199
Agent score
66%

What's inside Meridian

  1. Use a reverse proxy for SNI routing

    main

    A hardened architecture uses a reverse proxy (like nginx) to hide the proxy core (e.g., Xray) from direct internet exposure.

    In the Meridian stack, nginx uses its stream module at port 443 to perform SNI Routing:

    1. It inspects the Server Name Indication (SNI) field of the incoming TLS connection.
    2. If the SNI matches a proxy target (e.g., a VLESS+Reality connection), it forwards the traffic to the Xray core.
    3. If the request is standard HTTPS, it passes it to the http module to serve a decoy webpage.

    This allows the proxy to share port 443 with a normal website, making the server appear as a regular web server to outside observers.

  2. How Domain Mode with Cloudflare works

    main

    Meridian's domain mode allows users to use a domain name and a CDN (like Cloudflare) to increase resilience.

    Benefits:

    • IP Hiding: Cloudflare acts as a proxy, hiding the origin server's real IP address from censors.
    • CDN Fallback: Enables the use of VLESS over WebSockets (WSS). If the server's IP is blocked, users can still connect through the Cloudflare network.

    Traffic Flow:

    • Direct Reality Connections: Handled by nginx stream routing to Xray.
    • WSS/XHTTP Traffic: Flows through Cloudflare $\rightarrow$ nginx http $\rightarrow$ Xray's internal listener.

  3. Understand the Meridian CLI project structure

    main

    The CLI is a Python package located in src/meridian/ and is distributed via PyPI as meridian-vpn.

    Core Modules

    • cli.py: The Typer application responsible for subcommand registration.
    • commands/: Contains individual modules for each CLI subcommand.
    • credentials.py: Defines the ServerCredentials dataclass.
    • servers.py: Contains the ServerRegistry for managing known servers.
    • provision/: Implements the idempotent step pipeline for provisioning.

  4. How to use Relay Mode with Realm

    main

    For users facing high latency, Meridian supports a relay mode using Realm, a high-performance Layer 4 TCP forwarder. This allows setting up a lightweight entry point closer to the user.

    Setup Pattern:

    1. Relay Server: Runs only Realm on port 443. It does not run Xray or nginx. It performs raw TCP forwarding to the exit server.
    2. Exit Server: Runs the full Meridian stack (nginx + Xray).

    Security Note: The relay server only sees encrypted traffic and has no knowledge of the proxy keys or the contents of the connection.

  5. How SNI camouflage works

    main

    The SNI (Server Name Indication) target is the domain your server impersonates to hide TLS traffic from censors. This should be a popular website you do not own. When a censor probes your server, they see the certificate of the impersonated site.

    • Good targets: www.microsoft.com, www.twitch.tv, dl.google.com, github.com.
    • Avoid: apple.com or icloud.com (mismatched ASN ranges are easily detectable).

    To find optimal targets that match your server's ASN, use the scan command:

    meridian scan 1.2.3.4

    Note: Do not use your own domain as an --sni target; this defeats the purpose of impersonation.

  6. Understand Meridian's Service Topologies

    main

    Meridian supports three primary deployment topologies depending on your requirements for domains and censorship circumvention:

    Standalone Mode (No Domain)

    Used when you only have a server IP. It uses an ACME shortlived certificate (6-day validity) for the connection page and panel.

    • Traffic Flow: Nginx (stream module) listens on port 443 and routes traffic by SNI. If the SNI matches your reality_sni, it forwards raw TCP to Xray Reality. If the SNI is the server IP, it routes to the Nginx HTTP module on port 8443.

    Domain Mode

    Adds a CDN fallback path using VLESS+WSS. This allows traffic to flow through providers like Cloudflare, making the connection work even if the server IP is blocked.

    • Traffic Flow: Similar to Standalone, but includes a path for WebSocket (WSS) traffic routed through the domain to Xray.

    Relay Topology

    A lightweight setup for bypassing domestic restrictions. A relay node (running Realm) acts as a TCP forwarder. The client connects to the relay's domestic IP, which forwards raw TCP to the exit server abroad. Encryption remains end-to-end between the client and the exit server.

  7. Comparison of VPN protocols against DPI detection

    main

    Modern censorship uses Protocol Fingerprinting, Statistical Analysis, and Active Probing. The following table summarizes how different protocols perform against these methods:

    • OpenVPN: Fails against Protocol Fingerprinting (fixed handshake) and Statistical Analysis (high overhead).
    • WireGuard: Fails against Protocol Fingerprinting (fixed handshake structure).
    • Shadowsocks: Fails against Statistical Analysis (high entropy/randomness) and Active Probing (specific error responses).
    • VLESS+Reality: Survives all three methods by using TLS camouflage, a lightweight header, and uTLS browser impersonation.

  8. Understand connection protocols in Domain Mode

    main

    When using Domain Mode, Meridian provides three connection protocols with different routing behaviors. Users should follow the priority order to ensure the best performance and reliability:

    1. Reality (Primary): Direct connection to the server IP. This is the fastest option.
    2. XHTTP (Alternative): Routes through nginx on port 443.
    3. WSS (Backup): Routes through the Cloudflare CDN. This should only be used if the server IP is blocked.

  9. Understand Meridian's security design and credential storage

    main

    Meridian implements several security layers for credential management and system access:

    Credential Storage

    • Permissions: Credentials are stored in ~/.meridian/credentials/<IP>/ with 0600 permissions. The parent directory uses 0700 (owner-only) permissions.
    • Safety: Secrets are never passed through shell commands without shlex.quote() and are redacted from meridian doctor output.
    • Warning: Any application running as your user can read these files. If your local machine is compromised at the user level, these credentials are at risk.

    Access and Networking

    • Panel Access: The management panel is reverse-proxied by nginx at a secret HTTPS path. No SSH tunnel is required. You can find the Panel URL and credentials in ~/.meridian/credentials/<IP>/proxy.yml.
    • SSH: Password authentication is disabled by default.
    • Firewall: Meridian configures UFW with a deny-all-incoming policy, only opening ports 22, 80, and 443.
    • TLS: Certificates are managed by acme.sh via Let's Encrypt and served by nginx.
    • Docker: The 3x-ui image is pinned to a specific tested version.

  11. Proactive resilience strategies

    main

    To maximize uptime and prevent service disruption during IP blocks, implement these three layers of defense:

    1. Deploy a relay: Provides clients with a domestic entry point. If the exit IP is blocked, you can swap the exit behind the relay without touching clients.
      • Command: meridian relay deploy RELAY_IP --exit EXIT_IP
    2. Enable domain mode: Adds a WSS/CDN fallback via Cloudflare that works even if the server IP is blocked.
      • Command: meridian deploy EXIT_IP --domain proxy.example.com
    3. Use both: Provides maximum resilience by giving clients three connection paths: relay (domestic), CDN (Cloudflare), and direct (if unblocked).

  12. How Meridian's two-layer architecture works

    main

    Meridian uses a two-layer architecture to make a proxy server indistinguishable from a standard website. It consolidates all traffic handling into nginx and uses Xray for the core proxy tunnel.

    1. nginx (Traffic Dispatcher & Web Server): Handles all incoming traffic on port 443. It uses the stream module for Layer 4 SNI routing and the http module for Layer 7 TLS termination, static file serving, and reverse proxying.
    2. Xray (Proxy Tunnel): Handles the actual VLESS+Reality proxying. It receives raw TCP streams forwarded by nginx when the SNI matches the Reality target.

    This design ensures that if a user visits the server's IP in a browser, they see a legitimate website instead of a connection error, making the server much harder to detect via passive reconnaissance.