DOCSEARCHbyAlgolia
Submit Docs

MTProxyMax Documentation

repository·main·Indexed 20 days ago

https://github.com/samnet-dev/mtproxymax

A Telegram MTProto proxy management system powered by the Rust-based telemt engine. It features a single-script deployment, an interactive TUI, and advanced anti-censorship tools including FakeTLS V2, Anti-DPI packet padding, and a Kernel SYN Shield. The system includes performance tuning for TCP BBRv3, QoS bandwidth management, a voucher system for access control, and a multi-tier administrative role system for its Telegram management bot.

Tokens
12.6K
Snippets
38
Records
52
Agent score
23%

What's inside MTProxyMax

  1. Compare MTProxyMax features with other solutions

    main

    MTProxyMax v1.3 is a management platform designed for advanced proxy deployment, distinguishing itself from minimal solutions like mtg or the official Telegram MTProxy through its feature set.

    Key differentiators include:

    • Advanced Anti-DPI: FakeTLS V2, Active DPI Forensics (dpi-inspect), and Self-Healing Cover Watchdog.
    • User Management: Unlimited multi-user secrets, per-user limits (connections, IPs, quota, expiry), and bandwidth quotas.
    • Resilience: Autonomous upstream failover, 1-Click Emergency Evacuation (evacuate), and Emergency Lockdown Switch.
    • Operational Tools: Interactive TUI, Telegram Bot (21 commands), Live Dashboard (live-diag), and Prometheus metrics.
    • Network Control: Per-IP Bandwidth Shaping (QoS) via Linux tc, Kernel SYN Shield (Tarpit), and Proxy Chaining (SOCKS5/4).

  2. Understand the MTProxyMax architecture

    main

    MTProxyMax operates as a multi-component management platform. The core engine is telemt (a Rust/Tokio-based MTProto engine) running inside a Docker container, which handles FakeTLS and upstream routing (Direct or SOCKS5 chaining).

    Core Components

    • mtproxymax.sh: The primary entry point. A single bash script providing the CLI, TUI, and configuration management.
    • telemt: The high-performance Rust engine running within Docker.
    • Telegram bot service: An independent systemd service that polls the Telegram Bot API for commands.
    • Replication sync service: A systemd timer that uses rsync + SSH to push configurations from a Master server to Slave servers.
    • Prometheus endpoint: Exposes metrics on localhost:9090 for monitoring.

  3. Understand the MTProxyMax Feature Suites

    main

    MTProxyMax is organized into several functional suites that can be enabled or configured:

    • QoS & Bandwidth Shaping: Uses Hierarchical Token Bucket (htb) and Linux tc for per-account shaping via speed-limit.
    • Fleet Management: Centralized Master-Slave telemetry aggregation and multi-node health monitoring via fleet.
    • SSL Shield: Automated Let's Encrypt / openssl certificate issuance and ACME management via ssl-shield.
    • Cloud Backups: Automatic offloading to Telegram or multi-cloud (S3/R2/rclone) via backup-cloud.
    • Telegram Bot: Dual-tier bot providing public self-service (/start, /my_status, /voucher) and an Admin Control Plane (/mp_fleet, /mp_secrets, /mp_lockdown).
    • Anti-DPI & Stealth: Includes TCP BBRv3/ECN auto-tuning (bbr), packet padding (shield), reverse-proxy cover (cover-shield), and kernel SYN protection (shield).
    • Advanced Routing: Decoy routing (decoy), autonomous SNI hunting (auto-sni), and geo-fencing (geofence).

  4. Configure Master-Slave Replication

    main
    MTProxyMax supports Master-Slave replication to synchronize configurations across multiple servers. This is achieved using a systemd timer on the Master server that triggers an rsync over SSH to push the configuration to the Slave server(s).

  5. Manage proxy via Telegram Bot

    main

    You can manage your proxy from a mobile device using the Telegram Bot. First, set it up with:

    mtproxymax telegram setup

    Available Commands:

    CommandDescription
    /mp_statusProxy status, uptime, connections
    /mp_secretsList all users with active connections
    /mp_linkGet proxy details + QR code image
    /mp_add <label>Add new user
    /mp_remove <label>Delete user
    /mp_revoke <label>Revoke and purge a user secret immediately
    /mp_rotate <label>Generate new key for user
    /mp_enable <label>Re-enable disabled user
    /mp_disable <label>Temporarily disable user
    /mp_lockdown [on|off]Toggle emergency panic lockdown defensive posture
    /mp_digestView live executive health, posture, and traffic digest box
    /mp_limitsShow all user limits
    /mp_setlimitSet user limits
    /mp_trafficPer-user traffic breakdown
    /mp_upstreamsList proxy chains
    /mp_healthRun diagnostics
    /mp_restartRestart proxy
    /mp_updateCheck for updates
    /mp_helpShow all commands

    Automatic Alerts:

    • Emergency Lockdown notifications.
    • System Broadcasts via mtproxymax broadcast <msg>.
    • Proactive Expiry Alerts (7d, 3d, 24h before expiration).
    • Proxy status notifications (Down/Started/Restart attempts).
    • Periodic traffic reports.

  6. Configure Telegram Bot notifications

    main

    Set up a Telegram bot to receive status updates, alerts, and manual notifications:

    • mtproxymax telegram setup: Interactive wizard to configure the bot.
    • mtproxymax telegram status: Show current bot status.
    • mtproxymax telegram interval <hours>: Change the reporting interval (1-168h).
    • mtproxymax telegram alerts <on|off>: Enable or disable down/recovery alerts.
    • mtproxymax notify <message>: Send a custom message via the Telegram bot.
    • mtproxymax telegram label <name>: Change the server label used in notifications.
    mtproxymax telegram setup
mtproxymax notify "Server maintenance starting in 10 minutes"

  7. Configure Proxy Chaining (Upstream Routing)

    main

    Route outgoing MTProto traffic through intermediate servers (SOCKS5, SOCKS4, or direct) to bypass IP filtering or chain connections. This is useful for routing through V2Ray, Xray, Sing-box, Cloudflare WARP, or SSH tunnels.

    Command Syntax mtproxymax upstream add <label> <socks5|socks4|direct> <host:port> [username] [password] [weight] [interface]

    Examples

    1. Local SOCKS5 (e.g., V2Ray/Xray/X-UI on 127.0.0.1:1080):

    mtproxymax upstream add v2ray-tunnel socks5 127.0.0.1:1080 "" "" 10

    2. Authenticated SOCKS5 Relay:

    mtproxymax upstream add secure-relay socks5 127.0.0.1:1080 myuser mypass 10

    3. Load Balancing (Weight-based): Route 70% of traffic directly and 30% through a WARP tunnel:

    mtproxymax upstream add direct-route direct - - - 70
mtproxymax upstream add warp-route socks5 127.0.0.1:40000 "" "" 30

    Management & Testing

    • mtproxymax upstream list: View all registered upstreams and weights.
    • mtproxymax upstream test <label>: Perform a real-time TCP/MTProto handshake test over the specific upstream.
    • Autonomous Failover: Enable with mtproxymax failover on. If an upstream fails (high packet loss or drop), the system automatically switches to backups within 30 seconds without dropping active user connections.
    # Example: Local unauthenticated SOCKS5 proxy
mtproxymax upstream add v2ray-tunnel socks5 127.0.0.1:1080 "" "" 10

  8. System Requirements for MTProxyMax

    main

    Before installing MTProxyMax, ensure your environment meets the following requirements:

    RequirementDetails
    OSUbuntu, Debian, CentOS, RHEL, Fedora, Rocky, AlmaLinux, Alpine
    DockerAuto-installed if not present
    RAM256MB minimum
    AccessRoot required
    Bash4.2+

  9. Manage MTProxyMax after installation

    main

    Once installed, use the following commands to interact with the proxy manager:

    • mtproxymax: Opens the interactive TUI (Terminal User Interface) menu-driven setup.
    • mtproxymax status: Checks the current health and status of the proxy.
    mtproxymax           # Open interactive TUI
mtproxymax status    # Check proxy health

  10. Install MTProxyMax

    main

    You can install MTProxyMax using either a one-line automated script or a manual method. The installation process includes an interactive wizard to configure ports, domains, user secrets, and Telegram bot settings.

    ### One-Line Install
```bash
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/SamNet-dev/MTProxyMax/main/install.sh)"

    Manual Install

    curl -fsSL https://raw.githubusercontent.com/SamNet-dev/MTProxyMax/main/mtproxymax.sh -o mtproxymax
chmod +x mtproxymax
sudo ./mtproxymax install

  11. Configure advanced performance and Anti-DPI settings

    main

    Advanced network, kernel, and anti-censorship features can be toggled instantly without restarting the server or interrupting active connections. You can enable these via the interactive TUI or directly via CLI commands.

    Via TUI:

    1. Run mtproxymax.
    2. Select [p] Performance & Self-Healing Suite.
    3. Use keys [1], [2], [a], [b], or [c] to toggle specific shields or boosters.

    Via CLI:

    Use the mtproxymax <feature> on|off syntax.

  12. Optimize Kernel and Network Performance

    main

    Commands to tune the Linux kernel for high-performance proxying and low-latency connections.

    TCP and Congestion Control:

    • TCP BBR/Fast Open Booster: Activates Google's BBR and TCP Fast Open. mtproxymax tcp-boost on
    • TCP BBRv3 & ECN: Activates BBRv3, Fair Queueing, and ECN auto-tuning. mtproxymax bbr on
    • TCP Fast-Path: Enables window scaling, SACK, and Path MTU discovery. mtproxymax tcp-fastpath on

    Socket and Memory Tuning:

    • Socket Booster: Optimizes listen backlog (somaxconn) and buffer limits. mtproxymax socket-boost on
    • TCP Clean (Keep-Alive Reaper): Purges orphaned mobile sockets quickly. mtproxymax tcp-clean on
    • RAM Auto-Tuning: Automatically calculates safe TCP buffer ceilings and min_free_kbytes based on physical RAM. mtproxymax ram-tune auto
    • Emergency RAM/Socket Healer: Reclaims pagecache and prunes TIME_WAIT sockets without disrupting users. mtproxymax heal or mtproxymax auto-heal on

    CPU and Packet Processing:

    • CPU Tune: Distributes packet processing across CPU cores via RPS/RFS. mtproxymax cpu-tune on
    # Example: Enabling high-performance TCP settings
mtproxymax tcp-boost on
mtproxymax bbr on
mtproxymax socket-boost on