seriyps/mtproto_proxy

Telegram periodically closes TCP connections to the proxy (DC connection rotation), typically every 30–70 seconds. To prevent dropping all multiplexed clients, the proxy performs a transparent migration.

The Migration Process

1. Detection: The dying downstream connection (mtp_down_conn (old)) notifies the connection pool (mtp_dc_pool) that it is closing.
2. Replacement: The pool removes the old connection and spawns/connects a new downstream connection (mtp_down_conn (new)).
3. Notification: The old connection sends a migrate(OldDown) cast to all connected client handlers (mtp_handler).
4. Handler Behavior:
   • If the handler is idle: It performs a synchronous migrate(OldDown, self(), Opts) call to the pool. The pool removes the handler from the old connection's upstreams, sends an upstream_new cast to the new connection, and returns the new PID to the handler. The handler then updates its downstream reference.
   • If the handler is blocked in down_send: The handler receives an {error, migrating} response. In this case, the client is expected to reconnect and resend the data.

Split-mode Architecture

In front/back split mode, the mtp_handler resides on the front node, while mtp_dc_pool and mtp_down_conn reside on the back node. Because the proxy uses Erlang distribution, all inter-process communication (e.g., migrate casts, upstream_new casts, and gen_server calls) works transparently across nodes without requiring code changes. If a back-node restarts, process monitors ensure that all affected front-node handlers exit cleanly.

The mtproto_proxy uses a multi-layered architecture to manage connections between Telegram clients and Telegram Data Centres (DCs). The flow involves three primary actors:

1. mtp_handler: A process dedicated to a single Telegram client TCP connection. It handles protocol decoding (fake-TLS, obfuscated, or secure) and manages the transition from the hello stage to the tunnel stage.
2. mtp_dc_pool: A manager that maintains a pool of downstream connections for a specific DC.
3. mtp_down_conn: A multiplexed TCP connection that communicates directly with the upstream Telegram DC.

Connection Lifecycle

1. Handshake and Lookup

When a client connects, the mtp_handler performs a lookup to find the appropriate mtp_dc_pool.

• Single-node mode: The handler uses whereis(dc_to_pool_name(DcId)) to find the pool locally.
• Split mode (node_role = front / back): The handler uses Erlang distribution (erpc:call) to locate the pool on the BackNode. If the pool is not found, it falls back to the default DC defined in mtp_config.
• Once located, the handler calls mtp_dc_pool:get(Pool, self(), Opts) to receive a downstream process ID (Downstream pid).

2. Steady-State Data Exchange

Once the tunnel is established, data flows as follows:

• Client to Telegram: Client sends TCP data $\rightarrow$ mtp_handler calls mtp_down_conn:send(Down, Data) $\rightarrow$ mtp_down_conn sends RPC-framed data to the Telegram DC.
• Telegram to Client: Telegram DC sends data $\rightarrow$ mtp_down_conn casts {proxy_ans, Down, Data} to the mtp_handler $\rightarrow$ mtp_handler sends TCP data to the client.
• Acknowledgements: The handler sends mtp_down_conn:ack(Down, Count, Size) to the downstream connection to manage flow control.

3. Termination

When the client closes the TCP connection, the mtp_handler notifies the pool via mtp_dc_pool:return(Pool, self()), and the pool notifies the downstream connection via upstream_closed(Down, Handler).

Domain fronting allows the proxy to forward unrecognized TLS connections (like browser probes or DPI) to a real HTTPS host, making the proxy indistinguishable from a normal web server. This is controlled via the domain_fronting key in config/prod-sys.config.

Options for domain_fronting:

• off: Default. No forwarding.
• sni: Forward the connection to the host specified in the client's SNI field on port 443. Requires policy rules (like a whitelist) to prevent loops or abuse.
• "host:port": Forward all unrecognized connections to a specific fixed third-party host.

Example: Forwarding to a local Nginx server

To run the proxy alongside a real website on the same machine, configure Nginx to listen on 127.0.0.1:1443 with valid TLS certificates, then set the proxy to forward to that local address:

 {mtproto_proxy,
  [
   {domain_fronting, "127.0.0.1:1443"},
   {ports, [...]} 
  ]
 }

 {mtproto_proxy,
  [
   {domain_fronting, "127.0.0.1:1443"},
   {ports,
    [#{name => mtp_handler_1,
      ... 
    }]}
   ]
 }

The proxy supports several connection policies to control access via mtproto_proxy configuration. Policies are defined in the policy list within the mtproto_proxy configuration block.

Supported Policies

• {in_table, KEY, TABLE_NAME}: Whitelist. Only allow connections if KEY is present in TABLE_NAME.
• {not_in_table, KEY, TABLE_NAME}: Blacklist. Only allow connections if KEY is not present in TABLE_NAME.
• {max_connections, KEYS, NUMBER}: (Experimental) Rejects new connections if the number of existing connections matching KEYS exceeds NUMBER.

Note on max_connections: A single Telegram client typically opens 3 to 8 connections. To support $N$ unique users, set the limit to at least $8 imes N$.

Available Keys

• port_name: The proxy port name.
• client_ipv4: Client's IPv4 address (ignored on IPv6 ports).
• client_ipv6: Client's IPv6 address (ignored on IPv4 ports).
• {client_ipv4_subnet, MASK}: Client's IPv4 subnet (mask 8-32).
• {client_ipv6_subnet, MASK}: Client's IPv6 subnet (mask 32-128).
• tls_domain: Lowercase domain name from fake-TLS secret (ignored if not using fake-TLS).

Split-mode uses a Front server (domestic/neutral IP) to accept client connections and a Back server (foreign IP) to connect to Telegram. This helps bypass aggressive censorship.

Prerequisites

• Erlang/OTP 25+ on both servers.
• TCP connectivity between servers.
• Back server must have outbound access to Telegram.

Step 1: Secure the inter-server link

Choose one of two methods:

1. DPI-resistant tunnel (Recommended): Use Shadowsocks, VLESS/XRay, or Hysteria2. Use the tunnel interface addresses (e.g., front@10.8.0.1) in the node names.
2. TLS distribution: Use the provided scripts to generate mutual-TLS certificates.
   • Run ./scripts/gen_dist_certs.sh init /etc/mtproto-proxy/dist on the back server.
   • Run ./scripts/gen_dist_certs.sh add-node /etc/mtproto-proxy/dist <front_name> for each front server.
   • Distribute the generated .pem and .conf files to the respective servers.
   • Uncomment -proto_dist and -ssl_dist_optfile in vm.args.

Step 2: Configure the Back Server

1. Run make init-config ROLE=back.
2. In vm.args: Set -name back@<BACK_IP> and a strong -setcookie.
3. In sys.config: Set external_ip.

Step 3: Configure the Front Server

1. Run make init-config ROLE=front.
2. In vm.args: Set -name front@<FRONT_IP> and the same cookie as the back.
3. In sys.config: Set back_node to the back node name (e.g., 'back@10.8.0.2') and configure ports.

Step 4: Start the servers

Always start the back server first.

# On back server:
make ROLE=back && sudo make install && systemctl start mtproto-proxy

# On front server:
make ROLE=front && sudo make install && systemctl start mtproto-proxy

Policy tables (e.g., ip_blacklist or customer_domains) are internal databases created automatically on startup. Data in these tables is not preserved when the proxy restarts. You can manage these tables at runtime using the eval command.

Add a value to a table

/opt/mtp_proxy/bin/mtp_proxy eval 'mtp_policy_table:add(TABLE_NAME, KEY, "VALUE").'

Remove a value from a table

/opt/mtp_proxy/bin/mtp_proxy eval 'mtp_policy_table:del(TABLE_NAME, KEY, "VALUE").'

Example: Blacklisting an IP

1. Configure policy: {not_in_table, client_ipv4, ip_blacklist}
2. Add IP: /opt/mtp_proxy/bin/mtp_proxy eval 'mtp_policy_table:add(ip_blacklist, client_ipv4, "203.0.113.1").'

# Add an IP to a blacklist
/opt/mtp_proxy/bin/mtp_proxy eval 'mtp_policy_table:add(ip_blacklist, client_ipv4, "203.0.113.1").'

# Remove an IP from a blacklist
/opt/mtp_proxy/bin/mtp_proxy eval 'mtp_policy_table:del(ip_blacklist, client_ipv4, "203.0.113.1").'