telemt/docs/CONFIG_PARAMS.en.md

Telemt Config Parameters Reference

This document lists all configuration keys accepted by config.toml.

Note

This reference was drafted with the help of AI and cross-checked against the codebase (config schema, defaults, and validation logic).

Warning

The configuration parameters detailed in this document are intended for advanced users and fine-tuning purposes. Modifying these settings without a clear understanding of their function may lead to application instability or other unexpected behavior. Please proceed with caution and at your own risk.

Top-level keys

Key	Type	Default
include	String (special directive)	—
show_link	"*" or String[]	[] (ShowLink::None)
dc_overrides	Map<String, String or String[]>	{}
default_dc	u8	— (effective fallback: 2 in ME routing)

• include

  • Constraints / validation: Must be a single-line directive in the form include = "path/to/file.toml". Includes are expanded before TOML parsing. Maximum include depth is 10.

  • Description: Includes another TOML file with include = "relative/or/absolute/path.toml"; includes are processed recursively before parsing.

  • Example:

    include = "secrets.toml"
    

• show_link

  • Constraints / validation: Accepts "*" or an array of usernames. Empty array means "show none".

  • Description: Legacy top-level link visibility selector ("*" for all users or explicit usernames list).

  • Example:

    # show links for all configured users
    show_link = "*"
    
    # or: show links only for selected users
    # show_link = ["alice", "bob"]
    

• dc_overrides

  • Constraints / validation: Key must be a positive integer DC index encoded as string (e.g. "203"). Values must parse as SocketAddr (ip:port). Empty strings are ignored.

  • Description: Overrides DC endpoints for non-standard DCs; key is DC index string, value is one or more ip:port addresses.

  • Example:

    [dc_overrides]
    "201" = "149.154.175.50:443"
    "203" = ["149.154.175.100:443", "91.105.192.100:443"]
    

• default_dc

  • Constraints / validation: Intended range is 1..=5. If set out of range, runtime falls back to DC1 behavior in direct relay; Middle-End routing falls back to 2 when not set.

  • Description: Default DC index used for unmapped non-standard DCs.

  • Example:

    # When a client requests an unknown/non-standard DC with no override,
    # route it to this default cluster (1..=5).
    default_dc = 2
    

[general]

Key	Type	Default
data_path	String	—
prefer_ipv6	bool	false
fast_mode	bool	true
use_middle_proxy	bool	true
proxy_secret_path	String	"proxy-secret"
proxy_config_v4_cache_path	String	"cache/proxy-config-v4.txt"
proxy_config_v6_cache_path	String	"cache/proxy-config-v6.txt"
ad_tag	String	—
middle_proxy_nat_ip	IpAddr	—
middle_proxy_nat_probe	bool	true
middle_proxy_nat_stun	String	—
middle_proxy_nat_stun_servers	String[]	[]
stun_nat_probe_concurrency	usize	8
middle_proxy_pool_size	usize	8
middle_proxy_warm_standby	usize	16
me_init_retry_attempts	u32	0
me2dc_fallback	bool	true
me2dc_fast	bool	false
me_keepalive_enabled	bool	true
me_keepalive_interval_secs	u64	8
me_keepalive_jitter_secs	u64	2
me_keepalive_payload_random	bool	true
rpc_proxy_req_every	u64	0
me_writer_cmd_channel_capacity	usize	4096
me_route_channel_capacity	usize	768
me_c2me_channel_capacity	usize	1024
me_c2me_send_timeout_ms	u64	4000
me_reader_route_data_wait_ms	u64	2
me_d2c_flush_batch_max_frames	usize	32
me_d2c_flush_batch_max_bytes	usize	131072
me_d2c_flush_batch_max_delay_us	u64	500
me_d2c_ack_flush_immediate	bool	true
me_quota_soft_overshoot_bytes	u64	65536
me_d2c_frame_buf_shrink_threshold_bytes	usize	262144
direct_relay_copy_buf_c2s_bytes	usize	65536
direct_relay_copy_buf_s2c_bytes	usize	262144
crypto_pending_buffer	usize	262144
max_client_frame	usize	16777216
desync_all_full	bool	false
beobachten	bool	true
beobachten_minutes	u64	10
beobachten_flush_secs	u64	15
beobachten_file	String	"cache/beobachten.txt"
hardswap	bool	true
me_warmup_stagger_enabled	bool	true
me_warmup_step_delay_ms	u64	500
me_warmup_step_jitter_ms	u64	300
me_reconnect_max_concurrent_per_dc	u32	8
me_reconnect_backoff_base_ms	u64	500
me_reconnect_backoff_cap_ms	u64	30000
me_reconnect_fast_retry_count	u32	16
me_single_endpoint_shadow_writers	u8	2
me_single_endpoint_outage_mode_enabled	bool	true
me_single_endpoint_outage_disable_quarantine	bool	true
me_single_endpoint_outage_backoff_min_ms	u64	250
me_single_endpoint_outage_backoff_max_ms	u64	3000
me_single_endpoint_shadow_rotate_every_secs	u64	900
me_floor_mode	"static" or "adaptive"	"adaptive"
me_adaptive_floor_idle_secs	u64	90
me_adaptive_floor_min_writers_single_endpoint	u8	1
me_adaptive_floor_min_writers_multi_endpoint	u8	1
me_adaptive_floor_recover_grace_secs	u64	180
me_adaptive_floor_writers_per_core_total	u16	48
me_adaptive_floor_cpu_cores_override	u16	0
me_adaptive_floor_max_extra_writers_single_per_core	u16	1
me_adaptive_floor_max_extra_writers_multi_per_core	u16	2
me_adaptive_floor_max_active_writers_per_core	u16	64
me_adaptive_floor_max_warm_writers_per_core	u16	64
me_adaptive_floor_max_active_writers_global	u32	256
me_adaptive_floor_max_warm_writers_global	u32	256
upstream_connect_retry_attempts	u32	2
upstream_connect_retry_backoff_ms	u64	100
upstream_connect_budget_ms	u64	3000
upstream_unhealthy_fail_threshold	u32	5
upstream_connect_failfast_hard_errors	bool	false
stun_iface_mismatch_ignore	bool	false
unknown_dc_log_path	String	"unknown-dc.txt"
unknown_dc_file_log_enabled	bool	false
log_level	"debug", "verbose", "normal", or "silent"	"normal"
disable_colors	bool	false
me_socks_kdf_policy	"strict" or "compat"	"strict"
me_route_backpressure_base_timeout_ms	u64	25
me_route_backpressure_high_timeout_ms	u64	120
me_route_backpressure_high_watermark_pct	u8	80
me_health_interval_ms_unhealthy	u64	1000
me_health_interval_ms_healthy	u64	3000
me_admission_poll_ms	u64	1000
me_warn_rate_limit_ms	u64	5000
me_route_no_writer_mode	"async_recovery_failfast", "inline_recovery_legacy", or "hybrid_async_persistent"	"hybrid_async_persistent"
me_route_no_writer_wait_ms	u64	250
me_route_hybrid_max_wait_ms	u64	3000
me_route_blocking_send_timeout_ms	u64	250
me_route_inline_recovery_attempts	u32	3
me_route_inline_recovery_wait_ms	u64	3000
fast_mode_min_tls_record	usize	0
update_every	u64	300
me_reinit_every_secs	u64	900
me_hardswap_warmup_delay_min_ms	u64	1000
me_hardswap_warmup_delay_max_ms	u64	2000
me_hardswap_warmup_extra_passes	u8	3
me_hardswap_warmup_pass_backoff_base_ms	u64	500
me_config_stable_snapshots	u8	2
me_config_apply_cooldown_secs	u64	300
me_snapshot_require_http_2xx	bool	true
me_snapshot_reject_empty_map	bool	true
me_snapshot_min_proxy_for_lines	u32	1
proxy_secret_stable_snapshots	u8	2
proxy_secret_rotate_runtime	bool	true
me_secret_atomic_snapshot	bool	true
proxy_secret_len_max	usize	256
me_pool_drain_ttl_secs	u64	90
me_instadrain	bool	false
me_pool_drain_threshold	u64	32
me_pool_drain_soft_evict_enabled	bool	true
me_pool_drain_soft_evict_grace_secs	u64	10
me_pool_drain_soft_evict_per_writer	u8	2
me_pool_drain_soft_evict_budget_per_core	u16	16
me_pool_drain_soft_evict_cooldown_ms	u64	1000
me_bind_stale_mode	"never", "ttl", or "always"	"ttl"
me_bind_stale_ttl_secs	u64	90
me_pool_min_fresh_ratio	f32	0.8
me_reinit_drain_timeout_secs	u64	90
proxy_secret_auto_reload_secs	u64	3600
proxy_config_auto_reload_secs	u64	3600
me_reinit_singleflight	bool	true
me_reinit_trigger_channel	usize	64
me_reinit_coalesce_window_ms	u64	200
me_deterministic_writer_sort	bool	true
me_writer_pick_mode	"sorted_rr" or "p2c"	"p2c"
me_writer_pick_sample_size	u8	3
ntp_check	bool	true
ntp_servers	String[]	["pool.ntp.org"]
auto_degradation_enabled	bool	true
degradation_min_unavailable_dc_groups	u8	2

• data_path

  • Constraints / validation: String (optional).

  • Description: Optional runtime data directory path.

  • Example:

    [general]
    data_path = "/var/lib/telemt"
    

• prefer_ipv6

  • Constraints / validation: Deprecated. Use network.prefer.

  • Description: Deprecated legacy IPv6 preference flag migrated to network.prefer.

  • Example:

    [network]
    prefer = 6
    

• fast_mode

  • Constraints / validation: bool.

  • Description: Enables fast-path optimizations for traffic processing.

  • Example:

    [general]
    fast_mode = true
    

• use_middle_proxy

  • Constraints / validation: bool.

  • Description: Enables ME transport mode; if false, runtime falls back to direct DC routing.

  • Example:

    [general]
    use_middle_proxy = true
    

• proxy_secret_path

  • Constraints / validation: String. When omitted, the default path is "proxy-secret". Empty values are accepted by TOML/serde but will likely fail at runtime (invalid file path).

  • Description: Path to Telegram infrastructure proxy-secret cache file used by ME handshake/RPC auth. Telemt always tries a fresh download from https://core.telegram.org/getProxySecret first, caches it to this path on success, and falls back to reading the cached file (any age) on download failure.

  • Example:

    [general]
    proxy_secret_path = "proxy-secret"
    

• proxy_config_v4_cache_path

  • Constraints / validation: String. When set, must not be empty/whitespace-only.

  • Description: Optional disk cache path for raw getProxyConfig (IPv4) snapshot. At startup Telemt tries to fetch a fresh snapshot first; on fetch failure or empty snapshot it falls back to this cache file when present and non-empty.

  • Example:

    [general]
    proxy_config_v4_cache_path = "cache/proxy-config-v4.txt"
    

• proxy_config_v6_cache_path

  • Constraints / validation: String. When set, must not be empty/whitespace-only.

  • Description: Optional disk cache path for raw getProxyConfigV6 (IPv6) snapshot. At startup Telemt tries to fetch a fresh snapshot first; on fetch failure or empty snapshot it falls back to this cache file when present and non-empty.

  • Example:

    [general]
    proxy_config_v6_cache_path = "cache/proxy-config-v6.txt"
    

• ad_tag

  • Constraints / validation: String (optional). When set, must be exactly 32 hex characters; invalid values are disabled during config load.

  • Description: Global fallback sponsored-channel ad_tag (used when user has no override in access.user_ad_tags). An all-zero tag is accepted but has no effect (and is warned about) until replaced with a real tag from @MTProxybot.

  • Example:

    [general]
    ad_tag = "00112233445566778899aabbccddeeff"
    

• middle_proxy_nat_ip

  • Constraints / validation: IpAddr (optional).

  • Description: Manual public NAT IP override used as ME address material when set.

  • Example:

    [general]
    middle_proxy_nat_ip = "203.0.113.10"
    

• middle_proxy_nat_probe

  • Constraints / validation: bool. Effective probing is gated by network.stun_use (when network.stun_use = false, STUN probing is disabled even if this flag is true).

  • Description: Enables STUN-based NAT probing to discover public IP:port used by ME key derivation in NAT environments.

  • Example:

    [general]
    middle_proxy_nat_probe = true
    

• middle_proxy_nat_stun

  • Constraints / validation: Deprecated. Use network.stun_servers.

  • Description: Deprecated legacy single STUN server for NAT probing. During config load it is merged into network.stun_servers unless network.stun_servers is explicitly set.

  • Example:

    [network]
    stun_servers = ["stun.l.google.com:19302"]
    

• middle_proxy_nat_stun_servers

  • Constraints / validation: Deprecated. Use network.stun_servers.

  • Description: Deprecated legacy STUN list for NAT probing fallback. During config load it is merged into network.stun_servers unless network.stun_servers is explicitly set.

  • Example:

    [network]
    stun_servers = ["stun.l.google.com:19302"]
    

• stun_nat_probe_concurrency

  • Constraints / validation: Must be > 0.

  • Description: Maximum number of parallel STUN probes during NAT/public endpoint discovery.

  • Example:

    [general]
    stun_nat_probe_concurrency = 8
    

• middle_proxy_pool_size

  • Constraints / validation: usize. Effective value is max(value, 1) at runtime (so 0 behaves as 1).

  • Description: Target size of active ME writer pool.

  • Example:

    [general]
    middle_proxy_pool_size = 8
    

• middle_proxy_warm_standby

  • Constraints / validation: usize.

  • Description: Number of warm standby ME connections kept pre-initialized.

  • Example:

    [general]
    middle_proxy_warm_standby = 16
    

• me_init_retry_attempts

  • Constraints / validation: 0..=1_000_000 (0 means unlimited retries).

  • Description: Startup retries for ME pool initialization.

  • Example:

    [general]
    me_init_retry_attempts = 0
    

• me2dc_fallback

  • Constraints / validation: bool.

  • Description: Allows fallback from ME mode to direct DC when ME startup fails.

  • Example:

    [general]
    me2dc_fallback = true
    

• me2dc_fast

  • Constraints / validation: bool. Active only when use_middle_proxy = true and me2dc_fallback = true.

  • Description: Fast ME->Direct fallback mode for new sessions.

  • Example:

    [general]
    use_middle_proxy = true
    me2dc_fallback = true
    me2dc_fast = false
    

• me_keepalive_enabled

  • Constraints / validation: bool.

  • Description: Enables periodic ME keepalive padding frames.

  • Example:

    [general]
    me_keepalive_enabled = true
    

• me_keepalive_interval_secs

  • Constraints / validation: u64 (seconds).

  • Description: Base ME keepalive interval in seconds.

  • Example:

    [general]
    me_keepalive_interval_secs = 8
    

• me_keepalive_jitter_secs

  • Constraints / validation: u64 (seconds).

  • Description: Keepalive jitter in seconds to reduce synchronized bursts.

  • Example:

    [general]
    me_keepalive_jitter_secs = 2
    

• me_keepalive_payload_random

  • Constraints / validation: bool.

  • Description: Randomizes keepalive payload bytes instead of fixed zero payload.

  • Example:

    [general]
    me_keepalive_payload_random = true
    

• rpc_proxy_req_every

  • Constraints / validation: 0 or within 10..=300 (seconds).

  • Description: Interval for service RPC_PROXY_REQ activity signals to ME (0 disables).

  • Example:

    [general]
    rpc_proxy_req_every = 0
    

• me_writer_cmd_channel_capacity

  • Constraints / validation: Must be > 0.

  • Description: Capacity of per-writer command channel.

  • Example:

    [general]
    me_writer_cmd_channel_capacity = 4096
    

• me_route_channel_capacity

  • Constraints / validation: Must be > 0.

  • Description: Capacity of per-connection ME response route channel.

  • Example:

    [general]
    me_route_channel_capacity = 768
    

• me_c2me_channel_capacity

  • Constraints / validation: Must be > 0.

  • Description: Capacity of per-client command queue (client reader -> ME sender).

  • Example:

    [general]
    me_c2me_channel_capacity = 1024
    

• me_c2me_send_timeout_ms

  • Constraints / validation: 0..=60000 (milliseconds).

  • Description: Maximum wait for enqueueing client->ME commands when the per-client queue is full (0 keeps legacy unbounded wait).

  • Example:

    [general]
    me_c2me_send_timeout_ms = 4000
    

• me_reader_route_data_wait_ms

  • Constraints / validation: 0..=20 (milliseconds).

  • Description: Bounded wait for routing ME DATA to per-connection queue (0 = no wait).

  • Example:

    [general]
    me_reader_route_data_wait_ms = 2
    

• me_d2c_flush_batch_max_frames

  • Constraints / validation: Must be within 1..=512.

  • Description: Max ME->client frames coalesced before flush.

  • Example:

    [general]
    me_d2c_flush_batch_max_frames = 32
    

• me_d2c_flush_batch_max_bytes

  • Constraints / validation: Must be within 4096..=2097152 (bytes).

  • Description: Max ME->client payload bytes coalesced before flush.

  • Example:

    [general]
    me_d2c_flush_batch_max_bytes = 131072
    

• me_d2c_flush_batch_max_delay_us

  • Constraints / validation: 0..=5000 (microseconds).

  • Description: Max microsecond wait for coalescing more ME->client frames (0 disables timed coalescing).

  • Example:

    [general]
    me_d2c_flush_batch_max_delay_us = 500
    

• me_d2c_ack_flush_immediate

  • Constraints / validation: bool.

  • Description: Flushes client writer immediately after quick-ack write.

  • Example:

    [general]
    me_d2c_ack_flush_immediate = true
    

• me_quota_soft_overshoot_bytes

  • Constraints / validation: 0..=16777216 (bytes).

  • Description: Extra per-route quota allowance (bytes) tolerated before writer-side quota enforcement drops route data.

  • Example:

    [general]
    me_quota_soft_overshoot_bytes = 65536
    

• me_d2c_frame_buf_shrink_threshold_bytes

  • Constraints / validation: Must be within 4096..=16777216 (bytes).

  • Description: Threshold for shrinking oversized ME->client frame-aggregation buffers after flush.

  • Example:

    [general]
    me_d2c_frame_buf_shrink_threshold_bytes = 262144
    

• direct_relay_copy_buf_c2s_bytes

  • Constraints / validation: Must be within 4096..=1048576 (bytes).

  • Description: Copy buffer size for client->DC direction in direct relay.

  • Example:

    [general]
    direct_relay_copy_buf_c2s_bytes = 65536
    

• direct_relay_copy_buf_s2c_bytes

  • Constraints / validation: Must be within 8192..=2097152 (bytes).

  • Description: Copy buffer size for DC->client direction in direct relay.

  • Example:

    [general]
    direct_relay_copy_buf_s2c_bytes = 262144
    

• crypto_pending_buffer

  • Constraints / validation: usize (bytes).

  • Description: Max pending ciphertext buffer per client writer (bytes).

  • Example:

    [general]
    crypto_pending_buffer = 262144
    

• max_client_frame

  • Constraints / validation: usize (bytes).

  • Description: Maximum allowed client MTProto frame size (bytes).

  • Example:

    [general]
    max_client_frame = 16777216
    

• desync_all_full

  • Constraints / validation: bool.

  • Description: Emits full crypto-desync forensic logs for every event.

  • Example:

    [general]
    desync_all_full = false
    

• beobachten

  • Constraints / validation: bool.

  • Description: Enables per-IP forensic observation buckets.

  • Example:

    [general]
    beobachten = true
    

• beobachten_minutes

  • Constraints / validation: Must be > 0 (minutes).

  • Description: Retention window (minutes) for per-IP observation buckets.

  • Example:

    [general]
    beobachten_minutes = 10
    

• beobachten_flush_secs

  • Constraints / validation: Must be > 0 (seconds).

  • Description: Snapshot flush interval (seconds) for observation output file.

  • Example:

    [general]
    beobachten_flush_secs = 15
    

• beobachten_file

  • Constraints / validation: Must not be empty/whitespace-only.

  • Description: Observation snapshot output file path.

  • Example:

    [general]
    beobachten_file = "cache/beobachten.txt"
    

• hardswap

  • Constraints / validation: bool.

  • Description: Enables generation-based ME hardswap strategy.

  • Example:

    [general]
    hardswap = true
    

• me_warmup_stagger_enabled

  • Constraints / validation: bool.

  • Description: Staggers extra ME warmup dials to avoid connection spikes.

  • Example:

    [general]
    me_warmup_stagger_enabled = true
    

• me_warmup_step_delay_ms

  • Constraints / validation: u64 (milliseconds).

  • Description: Base delay in milliseconds between warmup dial steps.

  • Example:

    [general]
    me_warmup_step_delay_ms = 500
    

• me_warmup_step_jitter_ms

  • Constraints / validation: u64 (milliseconds).

  • Description: Additional random delay in milliseconds for warmup steps.

  • Example:

    [general]
    me_warmup_step_jitter_ms = 300
    

• me_reconnect_max_concurrent_per_dc

  • Constraints / validation: u32. Effective value is max(value, 1) at runtime (so 0 behaves as 1).

  • Description: Limits concurrent reconnect workers per DC during health recovery.

  • Example:

    [general]
    me_reconnect_max_concurrent_per_dc = 8
    

• me_reconnect_backoff_base_ms

  • Constraints / validation: u64 (milliseconds).

  • Description: Initial reconnect backoff in milliseconds.

  • Example:

    [general]
    me_reconnect_backoff_base_ms = 500
    

• me_reconnect_backoff_cap_ms

  • Constraints / validation: u64 (milliseconds).

  • Description: Maximum reconnect backoff cap in milliseconds.

  • Example:

    [general]
    me_reconnect_backoff_cap_ms = 30000
    

• me_reconnect_fast_retry_count

  • Constraints / validation: u32. Effective value is max(value, 1) at runtime (so 0 behaves as 1).

  • Description: Immediate retry budget before long backoff behavior applies.

  • Example:

    [general]
    me_reconnect_fast_retry_count = 16
    

• me_single_endpoint_shadow_writers

  • Constraints / validation: Must be within 0..=32.

  • Description: Additional reserve writers for DC groups with exactly one endpoint.

  • Example:

    [general]
    me_single_endpoint_shadow_writers = 2
    

• me_single_endpoint_outage_mode_enabled

  • Constraints / validation: bool.

  • Description: Enables aggressive outage recovery mode for DC groups with exactly one endpoint.

  • Example:

    [general]
    me_single_endpoint_outage_mode_enabled = true
    

• me_single_endpoint_outage_disable_quarantine

  • Constraints / validation: bool.

  • Description: Ignores endpoint quarantine while in single-endpoint outage mode.

  • Example:

    [general]
    me_single_endpoint_outage_disable_quarantine = true
    

• me_single_endpoint_outage_backoff_min_ms

  • Constraints / validation: Must be > 0 (milliseconds) and <= me_single_endpoint_outage_backoff_max_ms.

  • Description: Minimum reconnect backoff in single-endpoint outage mode.

  • Example:

    [general]
    me_single_endpoint_outage_backoff_min_ms = 250
    

• me_single_endpoint_outage_backoff_max_ms

  • Constraints / validation: Must be > 0 (milliseconds) and >= me_single_endpoint_outage_backoff_min_ms.

  • Description: Maximum reconnect backoff in single-endpoint outage mode.

  • Example:

    [general]
    me_single_endpoint_outage_backoff_max_ms = 3000
    

• me_single_endpoint_shadow_rotate_every_secs

  • Constraints / validation: u64 (seconds). 0 disables periodic shadow rotation.

  • Description: Periodic shadow writer rotation interval for single-endpoint DC groups.

  • Example:

    [general]
    me_single_endpoint_shadow_rotate_every_secs = 900
    

• me_floor_mode

  • Constraints / validation: "static" or "adaptive".

  • Description: Floor policy mode for ME writer targets.

  • Example:

    [general]
    me_floor_mode = "adaptive"
    

• me_adaptive_floor_idle_secs

  • Constraints / validation: u64 (seconds).

  • Description: Idle time before adaptive floor may reduce the single-endpoint writer target.

  • Example:

    [general]
    me_adaptive_floor_idle_secs = 90
    

• me_adaptive_floor_min_writers_single_endpoint

  • Constraints / validation: Must be within 1..=32.

  • Description: Minimum writer target for single-endpoint DC groups in adaptive floor mode.

  • Example:

    [general]
    me_adaptive_floor_min_writers_single_endpoint = 1
    

• me_adaptive_floor_min_writers_multi_endpoint

  • Constraints / validation: Must be within 1..=32.

  • Description: Minimum writer target for multi-endpoint DC groups in adaptive floor mode.

  • Example:

    [general]
    me_adaptive_floor_min_writers_multi_endpoint = 1
    

• me_adaptive_floor_recover_grace_secs

  • Constraints / validation: u64 (seconds).

  • Description: Grace period to hold static floor after activity in adaptive mode.

  • Example:

    [general]
    me_adaptive_floor_recover_grace_secs = 180
    

• me_adaptive_floor_writers_per_core_total

  • Constraints / validation: Must be > 0.

  • Description: Global ME writer budget per logical CPU core in adaptive mode.

  • Example:

    [general]
    me_adaptive_floor_writers_per_core_total = 48
    

• me_adaptive_floor_cpu_cores_override

  • Constraints / validation: u16. 0 uses runtime auto-detection.

  • Description: Override logical CPU core count used for adaptive floor calculations.

  • Example:

    [general]
    me_adaptive_floor_cpu_cores_override = 0
    

• me_adaptive_floor_max_extra_writers_single_per_core

  • Constraints / validation: u16.

  • Description: Per-core max extra writers above base required floor for single-endpoint DC groups.

  • Example:

    [general]
    me_adaptive_floor_max_extra_writers_single_per_core = 1
    

• me_adaptive_floor_max_extra_writers_multi_per_core

  • Constraints / validation: u16.

  • Description: Per-core max extra writers above base required floor for multi-endpoint DC groups.

  • Example:

    [general]
    me_adaptive_floor_max_extra_writers_multi_per_core = 2
    

• me_adaptive_floor_max_active_writers_per_core

  • Constraints / validation: Must be > 0.

  • Description: Hard cap for active ME writers per logical CPU core.

  • Example:

    [general]
    me_adaptive_floor_max_active_writers_per_core = 64
    

• me_adaptive_floor_max_warm_writers_per_core

  • Constraints / validation: Must be > 0.

  • Description: Hard cap for warm ME writers per logical CPU core.

  • Example:

    [general]
    me_adaptive_floor_max_warm_writers_per_core = 64
    

• me_adaptive_floor_max_active_writers_global

  • Constraints / validation: Must be > 0.

  • Description: Hard global cap for active ME writers.

  • Example:

    [general]
    me_adaptive_floor_max_active_writers_global = 256
    

• me_adaptive_floor_max_warm_writers_global

  • Constraints / validation: Must be > 0.

  • Description: Hard global cap for warm ME writers.

  • Example:

    [general]
    me_adaptive_floor_max_warm_writers_global = 256
    

• upstream_connect_retry_attempts

  • Constraints / validation: Must be > 0.

  • Description: Connect attempts for the selected upstream before returning error/fallback.

  • Example:

    [general]
    upstream_connect_retry_attempts = 2
    

• upstream_connect_retry_backoff_ms

  • Constraints / validation: u64 (milliseconds). 0 disables backoff delay (retries become immediate).

  • Description: Delay in milliseconds between upstream connect attempts.

  • Example:

    [general]
    upstream_connect_retry_backoff_ms = 100
    

• upstream_connect_budget_ms

  • Constraints / validation: Must be > 0 (milliseconds).

  • Description: Total wall-clock budget in milliseconds for one upstream connect request across retries.

  • Example:

    [general]
    upstream_connect_budget_ms = 3000
    

• upstream_unhealthy_fail_threshold

  • Constraints / validation: Must be > 0.

  • Description: Consecutive failed requests before upstream is marked unhealthy.

  • Example:

    [general]
    upstream_unhealthy_fail_threshold = 5
    

• upstream_connect_failfast_hard_errors

  • Constraints / validation: bool.

  • Description: When true, skips additional retries for hard non-transient upstream connect errors.

  • Example:

    [general]
    upstream_connect_failfast_hard_errors = false
    

• stun_iface_mismatch_ignore

  • Constraints / validation: bool.

  • Description: Compatibility flag reserved for future use. Currently this key is parsed but not used by the runtime.

  • Example:

    [general]
    stun_iface_mismatch_ignore = false
    

• unknown_dc_log_path

  • Constraints / validation: String (optional). Must be a safe path (no .. components, parent directory must exist); unsafe paths are rejected at runtime.

  • Description: Log file path for unknown (non-standard) DC requests when unknown_dc_file_log_enabled = true. Omit this key to disable file logging.

  • Example:

    [general]
    unknown_dc_log_path = "unknown-dc.txt"
    

• unknown_dc_file_log_enabled

  • Constraints / validation: bool.

  • Description: Enables unknown-DC file logging (writes dc_idx=<N> lines). Requires unknown_dc_log_path to be set and, on non-Unix platforms, may be unsupported. Logging is deduplicated and capped (only the first ~1024 distinct unknown DC indices are recorded).

  • Example:

    [general]
    unknown_dc_file_log_enabled = false
    

• log_level

  • Constraints / validation: "debug", "verbose", "normal", or "silent".

  • Description: Runtime logging verbosity level (used when RUST_LOG is not set). If RUST_LOG is set in the environment, it takes precedence over this setting.

  • Example:

    [general]
    log_level = "normal"
    

• disable_colors

  • Constraints / validation: bool.

  • Description: Disables ANSI colors in logs (useful for files/systemd). This affects log formatting only and does not change the log level/filtering.

  • Example:

    [general]
    disable_colors = false
    

• me_socks_kdf_policy

  • Constraints / validation: "strict" or "compat".

  • Description: SOCKS-bound KDF fallback policy for Middle-End handshake.

  • Example:

    [general]
    me_socks_kdf_policy = "strict"
    

• me_route_backpressure_base_timeout_ms

  • Constraints / validation: Must be within 1..=5000 (milliseconds).

  • Description: Base backpressure timeout in milliseconds for ME route-channel send.

  • Example:

    [general]
    me_route_backpressure_base_timeout_ms = 25
    

• me_route_backpressure_high_timeout_ms

  • Constraints / validation: Must be within 1..=5000 (milliseconds) and >= me_route_backpressure_base_timeout_ms.

  • Description: High backpressure timeout in milliseconds when queue occupancy is above watermark.

  • Example:

    [general]
    me_route_backpressure_high_timeout_ms = 120
    

• me_route_backpressure_high_watermark_pct

  • Constraints / validation: Must be within 1..=100 (percent).

  • Description: Queue occupancy percent threshold for switching to high backpressure timeout.

  • Example:

    [general]
    me_route_backpressure_high_watermark_pct = 80
    

• me_health_interval_ms_unhealthy

  • Constraints / validation: Must be > 0 (milliseconds).

  • Description: Health monitor interval while ME writer coverage is degraded.

  • Example:

    [general]
    me_health_interval_ms_unhealthy = 1000
    

• me_health_interval_ms_healthy

  • Constraints / validation: Must be > 0 (milliseconds).

  • Description: Health monitor interval while ME writer coverage is stable/healthy.

  • Example:

    [general]
    me_health_interval_ms_healthy = 3000
    

• me_admission_poll_ms

  • Constraints / validation: Must be > 0 (milliseconds).

  • Description: Poll interval for conditional-admission state checks.

  • Example:

    [general]
    me_admission_poll_ms = 1000
    

• me_warn_rate_limit_ms

  • Constraints / validation: Must be > 0 (milliseconds).

  • Description: Cooldown for repetitive ME warning logs.

  • Example:

    [general]
    me_warn_rate_limit_ms = 5000
    

• me_route_no_writer_mode

  • Constraints / validation: "async_recovery_failfast", "inline_recovery_legacy", or "hybrid_async_persistent".

  • Description: ME route behavior when no writer is immediately available.

  • Example:

    [general]
    me_route_no_writer_mode = "hybrid_async_persistent"
    

• me_route_no_writer_wait_ms

  • Constraints / validation: Must be within 10..=5000 (milliseconds).

  • Description: Max wait time used by async-recovery failfast mode before falling back.

  • Example:

    [general]
    me_route_no_writer_wait_ms = 250
    

• me_route_hybrid_max_wait_ms

  • Constraints / validation: Must be within 50..=60000 (milliseconds).

  • Description: Maximum cumulative wait in hybrid no-writer mode before failfast fallback.

  • Example:

    [general]
    me_route_hybrid_max_wait_ms = 3000
    

• me_route_blocking_send_timeout_ms

  • Constraints / validation: Must be within 0..=5000 (milliseconds). 0 keeps legacy unbounded wait behavior.

  • Description: Maximum wait for blocking route-channel send fallback.

  • Example:

    [general]
    me_route_blocking_send_timeout_ms = 250
    

• me_route_inline_recovery_attempts

  • Constraints / validation: Must be > 0.

  • Description: Number of inline recovery attempts in legacy mode.

  • Example:

    [general]
    me_route_inline_recovery_attempts = 3
    

• me_route_inline_recovery_wait_ms

  • Constraints / validation: Must be within 10..=30000 (milliseconds).

  • Description: Max inline recovery wait in legacy mode.

  • Example:

    [general]
    me_route_inline_recovery_wait_ms = 3000
    

• fast_mode_min_tls_record

  • Constraints / validation: usize (bytes). 0 disables the limit.

  • Description: Minimum TLS record size when fast-mode coalescing is enabled.

  • Example:

    [general]
    fast_mode_min_tls_record = 0
    

• update_every

  • Constraints / validation: u64 (seconds). If set, must be > 0. If this key is not explicitly set, legacy proxy_secret_auto_reload_secs and proxy_config_auto_reload_secs may be used (their effective minimum must be > 0).

  • Description: Unified refresh interval for ME updater tasks (getProxyConfig, getProxyConfigV6, getProxySecret). When set, it overrides legacy proxy reload intervals.

  • Example:

    [general]
    update_every = 300
    

• me_reinit_every_secs

  • Constraints / validation: Must be > 0 (seconds).

  • Description: Periodic interval for zero-downtime ME reinit cycle.

  • Example:

    [general]
    me_reinit_every_secs = 900
    

• me_hardswap_warmup_delay_min_ms

  • Constraints / validation: u64 (milliseconds). Must be <= me_hardswap_warmup_delay_max_ms.

  • Description: Lower bound for hardswap warmup dial spacing.

  • Example:

    [general]
    me_hardswap_warmup_delay_min_ms = 1000
    

• me_hardswap_warmup_delay_max_ms

  • Constraints / validation: Must be > 0 (milliseconds).

  • Description: Upper bound for hardswap warmup dial spacing.

  • Example:

    [general]
    me_hardswap_warmup_delay_max_ms = 2000
    

• me_hardswap_warmup_extra_passes

  • Constraints / validation: Must be within [0, 10].

  • Description: Additional warmup passes after the base pass in one hardswap cycle.

  • Example:

    [general]
    # default: 3 (allowed range: 0..=10)
    me_hardswap_warmup_extra_passes = 3
    

• me_hardswap_warmup_pass_backoff_base_ms

  • Constraints / validation: u64 (milliseconds). Must be > 0.

  • Description: Base backoff between extra hardswap warmup passes when the floor is still incomplete.

  • Example:

    [general]
    # default: 500
    me_hardswap_warmup_pass_backoff_base_ms = 500
    

• me_config_stable_snapshots

  • Constraints / validation: Must be > 0.

  • Description: Number of identical ME config snapshots required before apply.

  • Example:

    [general]
    # require 3 identical snapshots before applying ME endpoint map updates
    me_config_stable_snapshots = 3
    

• me_config_apply_cooldown_secs

  • Constraints / validation: u64.

  • Description: Cooldown between applied ME endpoint-map updates. 0 disables the cooldown.

  • Example:

    [general]
    # allow applying stable snapshots immediately (no cooldown)
    me_config_apply_cooldown_secs = 0
    

• me_snapshot_require_http_2xx

  • Constraints / validation: bool.

  • Description: Requires 2xx HTTP responses for applying ME config snapshots. When false, non-2xx responses may still be parsed/considered by the updater.

  • Example:

    [general]
    # allow applying snapshots even when the HTTP status is non-2xx
    me_snapshot_require_http_2xx = false
    

• me_snapshot_reject_empty_map

  • Constraints / validation: bool.

  • Description: Rejects empty ME config snapshots (no endpoints). When false, an empty snapshot can be applied (subject to other gates), which may temporarily reduce/clear the ME map.

  • Example:

    [general]
    # allow applying empty snapshots (use with care)
    me_snapshot_reject_empty_map = false
    

• me_snapshot_min_proxy_for_lines

  • Constraints / validation: Must be > 0.

  • Description: Minimum parsed proxy_for rows required to accept snapshot.

  • Example:

    [general]
    # require at least 10 proxy_for rows before accepting a snapshot
    me_snapshot_min_proxy_for_lines = 10
    

• proxy_secret_stable_snapshots

  • Constraints / validation: Must be > 0.

  • Description: Number of identical proxy-secret snapshots required before rotation.

  • Example:

    [general]
    # require 2 identical getProxySecret snapshots before rotating at runtime
    proxy_secret_stable_snapshots = 2
    

• proxy_secret_rotate_runtime

  • Constraints / validation: bool.

  • Description: Enables runtime proxy-secret rotation from updater snapshots.

  • Example:

    [general]
    # disable runtime proxy-secret rotation (startup still uses proxy_secret_path/proxy_secret_len_max)
    proxy_secret_rotate_runtime = false
    

• me_secret_atomic_snapshot

  • Constraints / validation: bool.

  • Description: Keeps selector and secret bytes from the same snapshot atomically. When general.use_middle_proxy = true, this is auto-enabled during config load to keep ME KDF material coherent.

  • Example:

    [general]
    # NOTE: when use_middle_proxy=true, Telemt will auto-enable this during load
    me_secret_atomic_snapshot = false
    

• proxy_secret_len_max

  • Constraints / validation: Must be within [32, 4096].

  • Description: Upper length limit (bytes) for accepted proxy-secret during startup and runtime refresh.

  • Example:

    [general]
    # default: 256 (bytes)
    proxy_secret_len_max = 256
    

• me_pool_drain_ttl_secs

  • Constraints / validation: u64 (seconds). 0 disables the drain-TTL window (and suppresses drain-TTL warnings for non-empty draining writers).

  • Description: Drain-TTL time window for stale ME writers after endpoint map changes. During the TTL, stale writers may be used only as fallback for new bindings (depending on bind policy).

  • Example:

    [general]
    # disable drain TTL (draining writers won't emit "past drain TTL" warnings)
    me_pool_drain_ttl_secs = 0
    

• me_instadrain

  • Constraints / validation: bool.

  • Description: Forces draining stale writers to be removed on the next cleanup tick, bypassing TTL/deadline waiting.

  • Example:

    [general]
    # default: false
    me_instadrain = false
    

• me_pool_drain_threshold

  • Constraints / validation: u64. Set to 0 to disable threshold-based cleanup.

  • Description: Maximum number of draining stale writers before oldest ones are force-closed in batches.

  • Example:

    [general]
    # default: 32
    me_pool_drain_threshold = 32
    

• me_pool_drain_soft_evict_enabled

  • Constraints / validation: bool.

  • Description: Enables gradual soft-eviction of stale writers during drain/reinit instead of immediate hard close.

  • Example:

    [general]
    # default: true
    me_pool_drain_soft_evict_enabled = true
    

• me_pool_drain_soft_evict_grace_secs

  • Constraints / validation: u64 (seconds). Must be within [0, 3600].

  • Description: Extra grace (after drain TTL) before soft-eviction stage starts.

  • Example:

    [general]
    # default: 10
    me_pool_drain_soft_evict_grace_secs = 10
    

• me_pool_drain_soft_evict_per_writer

  • Constraints / validation: 1..=16.

  • Description: Maximum stale routes soft-evicted per writer in one eviction pass.

  • Example:

    [general]
    # default: 2
    me_pool_drain_soft_evict_per_writer = 2
    

• me_pool_drain_soft_evict_budget_per_core

  • Constraints / validation: 1..=64.

  • Description: Per-core budget limiting aggregate soft-eviction work per pass.

  • Example:

    [general]
    # default: 16
    me_pool_drain_soft_evict_budget_per_core = 16
    

• me_pool_drain_soft_evict_cooldown_ms

  • Constraints / validation: u64 (milliseconds). Must be > 0.

  • Description: Cooldown between repetitive soft-eviction on the same writer.

  • Example:

    [general]
    # default: 1000
    me_pool_drain_soft_evict_cooldown_ms = 1000
    

• me_bind_stale_mode

  • Constraints / validation: "never", "ttl", or "always".

  • Description: Policy for new binds on stale draining writers.

  • Example:

    [general]
    # allow stale binds only for a limited time window
    me_bind_stale_mode = "ttl"
    

• me_bind_stale_ttl_secs

  • Constraints / validation: u64.

  • Description: TTL for stale bind allowance when stale mode is ttl.

  • Example:

    [general]
    me_bind_stale_mode = "ttl"
    me_bind_stale_ttl_secs = 90
    

• me_pool_min_fresh_ratio

  • Constraints / validation: Must be within [0.0, 1.0].

  • Description: Minimum fresh desired-DC coverage ratio before stale writers are drained.

  • Example:

    [general]
    # require >=90% desired-DC coverage before draining stale writers
    me_pool_min_fresh_ratio = 0.9
    

• me_reinit_drain_timeout_secs

  • Constraints / validation: u64. 0 uses the runtime safety fallback force-close timeout. If > 0 and < me_pool_drain_ttl_secs, runtime bumps it to TTL.

  • Description: Force-close timeout for draining stale writers. When set to 0, the effective timeout is the runtime safety fallback (300 seconds).

  • Example:

    [general]
    # use runtime safety fallback force-close timeout (300s)
    me_reinit_drain_timeout_secs = 0
    

• proxy_secret_auto_reload_secs

  • Constraints / validation: Deprecated. Use general.update_every. When general.update_every is not explicitly set, the effective legacy refresh interval is min(proxy_secret_auto_reload_secs, proxy_config_auto_reload_secs) and must be > 0.

  • Description: Deprecated legacy proxy-secret refresh interval. Used only when general.update_every is not set.

  • Example:

    [general]
    # legacy mode: omit update_every to use proxy_*_auto_reload_secs
    proxy_secret_auto_reload_secs = 600
    proxy_config_auto_reload_secs = 120
    # effective updater interval = min(600, 120) = 120 seconds
    

• proxy_config_auto_reload_secs

  • Constraints / validation: Deprecated. Use general.update_every. When general.update_every is not explicitly set, the effective legacy refresh interval is min(proxy_secret_auto_reload_secs, proxy_config_auto_reload_secs) and must be > 0.

  • Description: Deprecated legacy ME config refresh interval. Used only when general.update_every is not set.

  • Example:

    [general]
    # legacy mode: omit update_every to use proxy_*_auto_reload_secs
    proxy_secret_auto_reload_secs = 600
    proxy_config_auto_reload_secs = 120
    # effective updater interval = min(600, 120) = 120 seconds
    

• me_reinit_singleflight

  • Constraints / validation: bool.

  • Description: Serializes ME reinit cycles across trigger sources.

  • Example:

    [general]
    me_reinit_singleflight = true
    

• me_reinit_trigger_channel

  • Constraints / validation: Must be > 0.

  • Description: Trigger queue capacity for reinit scheduler.

  • Example:

    [general]
    me_reinit_trigger_channel = 64
    

• me_reinit_coalesce_window_ms

  • Constraints / validation: u64.

  • Description: Trigger coalescing window before starting reinit (ms).

  • Example:

    [general]
    me_reinit_coalesce_window_ms = 200
    

• me_deterministic_writer_sort

  • Constraints / validation: bool.

  • Description: Enables deterministic candidate sort for writer binding path.

  • Example:

    [general]
    me_deterministic_writer_sort = true
    

• me_writer_pick_mode

  • Constraints / validation: "sorted_rr" or "p2c".

  • Description: Writer selection mode for route bind path.

  • Example:

    [general]
    me_writer_pick_mode = "p2c"
    

• me_writer_pick_sample_size

  • Constraints / validation: 2..=4.

  • Description: Number of candidates sampled by picker in p2c mode.

  • Example:

    [general]
    me_writer_pick_mode = "p2c"
    me_writer_pick_sample_size = 3
    

• ntp_check

  • Constraints / validation: bool.

  • Description: Reserved for future use. Currently this key is parsed but not used by the runtime.

  • Example:

    [general]
    ntp_check = true
    

• ntp_servers

  • Constraints / validation: String[].

  • Description: Reserved for future use. Currently this key is parsed but not used by the runtime.

  • Example:

    [general]
    ntp_servers = ["pool.ntp.org"]
    

• auto_degradation_enabled

  • Constraints / validation: bool.

  • Description: Reserved for future use. Currently this key is parsed but not used by the runtime.

  • Example:

    [general]
    auto_degradation_enabled = true
    

• degradation_min_unavailable_dc_groups

  • Constraints / validation: u8.

  • Description: Reserved for future use. Currently this key is parsed but not used by the runtime.

  • Example:

    [general]
    degradation_min_unavailable_dc_groups = 2
    

[general.modes]

Key	Type	Default
classic	bool	false
secure	bool	false
tls	bool	true

• classic

  • Constraints / validation: bool.

  • Description: Enables classic MTProxy mode.

  • Example:

    [general.modes]
    classic = true
    

• secure

  • Constraints / validation: bool.

  • Description: Enables secure mode.

  • Example:

    [general.modes]
    secure = true
    

• tls

  • Constraints / validation: bool.

  • Description: Enables TLS mode.

  • Example:

    [general.modes]
    tls = true
    

[general.links]

Key	Type	Default
show	"*" or String[]	"*"
public_host	String	—
public_port	u16	—

• show

  • Constraints / validation: "*" or String[]. An empty array means "show none".

  • Description: Selects users whose tg:// proxy links are shown at startup.

  • Example:

    [general.links]
    show = "*"
    # or:
    # show = ["alice", "bob"]
    

• public_host

  • Constraints / validation: String (optional).

  • Description: Public hostname/IP override used for generated tg:// links (overrides detected IP).

  • Example:

    [general.links]
    public_host = "proxy.example.com"
    

• public_port

  • Constraints / validation: u16 (optional).

  • Description: Public port override used for generated tg:// links (overrides server.port).

  • Example:

    [general.links]
    public_port = 443
    

[general.telemetry]

Key	Type	Default
core_enabled	bool	true
user_enabled	bool	true
me_level	"silent", "normal", or "debug"	"normal"

• core_enabled

  • Constraints / validation: bool.

  • Description: Enables core hot-path telemetry counters.

  • Example:

    [general.telemetry]
    core_enabled = true
    

• user_enabled

  • Constraints / validation: bool.

  • Description: Enables per-user telemetry counters.

  • Example:

    [general.telemetry]
    user_enabled = true
    

• me_level

  • Constraints / validation: "silent", "normal", or "debug".

  • Description: Middle-End telemetry verbosity level.

  • Example:

    [general.telemetry]
    me_level = "normal"
    

[network]

Key	Type	Default
ipv4	bool	true
ipv6	bool	false
prefer	u8	4
multipath	bool	false
stun_use	bool	true
stun_servers	String[]	Built-in STUN list (13 hosts)
stun_tcp_fallback	bool	true
http_ip_detect_urls	String[]	["https://ifconfig.me/ip", "https://api.ipify.org"]
cache_public_ip_path	String	"cache/public_ip.txt"
dns_overrides	String[]	[]

• ipv4

  • Constraints / validation: bool.

  • Description: Enables IPv4 networking.

  • Example:

    [network]
    ipv4 = true
    

• ipv6

  • Constraints / validation: bool.

  • Description: Enables/disables IPv6 networking. When omitted, defaults to false.

  • Example:

    [network]
    # enable IPv6 explicitly
    ipv6 = true
    
    # or: disable IPv6 explicitly
    # ipv6 = false
    

• prefer

  • Constraints / validation: Must be 4 or 6. If prefer = 4 while ipv4 = false, Telemt forces prefer = 6. If prefer = 6 while ipv6 = false, Telemt forces prefer = 4.

  • Description: Preferred IP family for selection when both families are available.

  • Example:

    [network]
    prefer = 6
    

• multipath

  • Constraints / validation: bool.

  • Description: Enables multipath behavior where supported by the platform and runtime.

  • Example:

    [network]
    multipath = true
    

• stun_use

  • Constraints / validation: bool.

  • Description: Global STUN switch; when false, STUN probing is disabled and only non-STUN detection remains.

  • Example:

    [network]
    stun_use = false
    

• stun_servers

  • Constraints / validation: String[]. Values are trimmed; empty values are removed; list is deduplicated. If this key is not explicitly set, Telemt keeps the built-in default STUN list.

  • Description: STUN servers list for public IP discovery.

  • Example:

    [network]
    stun_servers = [
      "stun.l.google.com:19302",
      "stun.stunprotocol.org:3478",
    ]
    

• stun_tcp_fallback

  • Constraints / validation: bool.

  • Description: Enables TCP fallback for STUN when the UDP path is blocked/unavailable.

  • Example:

    [network]
    stun_tcp_fallback = true
    

• http_ip_detect_urls

  • Constraints / validation: String[].

  • Description: HTTP endpoints used for public IP detection (fallback after STUN).

  • Example:

    [network]
    http_ip_detect_urls = ["https://ifconfig.me/ip", "https://api.ipify.org"]
    

• cache_public_ip_path

  • Constraints / validation: String.

  • Description: File path used to cache the detected public IP.

  • Example:

    [network]
    cache_public_ip_path = "cache/public_ip.txt"
    

• dns_overrides

  • Constraints / validation: String[]. Each entry must use host:port:ip format.

    • host: domain name (must be non-empty and must not contain :)
    • port: u16
    • ip: IPv4 (1.2.3.4) or bracketed IPv6 ([2001:db8::1]). Unbracketed IPv6 is rejected.

  • Description: Runtime DNS overrides for host:port targets. Useful for forcing specific IPs for given upstream domains without touching system DNS.

  • Example:

    [network]
    dns_overrides = [
      "example.com:443:127.0.0.1",
      "example.net:8443:[2001:db8::10]",
    ]
    

[server]

Key	Type	Default
port	u16	443
listen_addr_ipv4	String	"0.0.0.0"
listen_addr_ipv6	String	"::"
listen_unix_sock	String	—
listen_unix_sock_perm	String	—
listen_tcp	bool	— (auto)
proxy_protocol	bool	false
proxy_protocol_header_timeout_ms	u64	500
proxy_protocol_trusted_cidrs	IpNetwork[]	[]
metrics_port	u16	—
metrics_listen	String	—
metrics_whitelist	IpNetwork[]	["127.0.0.1/32", "::1/128"]
max_connections	u32	10000
accept_permit_timeout_ms	u64	250

• port

  • Constraints / validation: u16.

  • Description: Main proxy listen port (TCP).

  • Example:

    [server]
    port = 443
    

• listen_addr_ipv4

  • Constraints / validation: String (optional). When set, must be a valid IPv4 address string.

  • Description: IPv4 bind address for TCP listener (omit this key to disable IPv4 bind).

  • Example:

    [server]
    listen_addr_ipv4 = "0.0.0.0"
    

• listen_addr_ipv6

  • Constraints / validation: String (optional). When set, must be a valid IPv6 address string.

  • Description: IPv6 bind address for TCP listener (omit this key to disable IPv6 bind).

  • Example:

    [server]
    listen_addr_ipv6 = "::"
    

• listen_unix_sock

  • Constraints / validation: String (optional). Must not be empty when set. Unix only.

  • Description: Unix socket path for listener. When set, server.listen_tcp defaults to false (unless explicitly overridden).

  • Example:

    [server]
    listen_unix_sock = "/run/telemt.sock"
    

• listen_unix_sock_perm

  • Constraints / validation: String (optional). When set, should be an octal permission string like "0666" or "0777".

  • Description: Optional Unix socket file permissions applied after bind (chmod). When omitted, permissions are not changed (inherits umask).

  • Example:

    [server]
    listen_unix_sock = "/run/telemt.sock"
    listen_unix_sock_perm = "0666"
    

• listen_tcp

  • Constraints / validation: bool (optional). When omitted, Telemt auto-detects:

    • true when listen_unix_sock is not set
    • false when listen_unix_sock is set

  • Description: Explicit TCP listener enable/disable override.

  • Example:

    [server]
    # force-enable TCP even when also binding a unix socket
    listen_unix_sock = "/run/telemt.sock"
    listen_tcp = true
    

• proxy_protocol

  • Constraints / validation: bool.

  • Description: Enables HAProxy PROXY protocol parsing on incoming connections (PROXY v1/v2). When enabled, client source address is taken from the PROXY header.

  • Example:

    [server]
    proxy_protocol = true
    

• proxy_protocol_header_timeout_ms

  • Constraints / validation: Must be > 0 (milliseconds).

  • Description: Timeout for reading and parsing PROXY protocol headers (ms).

  • Example:

    [server]
    proxy_protocol = true
    proxy_protocol_header_timeout_ms = 500
    

• proxy_protocol_trusted_cidrs

  • Constraints / validation: IpNetwork[].

    • If omitted, defaults to trust-all CIDRs (0.0.0.0/0 and ::/0).
    • If explicitly set to an empty array, all PROXY headers are rejected.

  • Description: Trusted source CIDRs allowed to provide PROXY protocol headers (security control).

  • Example:

    [server]
    proxy_protocol = true
    proxy_protocol_trusted_cidrs = ["127.0.0.1/32", "10.0.0.0/8"]
    

• metrics_port

  • Constraints / validation: u16 (optional).

  • Description: Prometheus-compatible metrics endpoint port. When set, enables the metrics listener (bind behavior can be overridden by metrics_listen).

  • Example:

    [server]
    metrics_port = 9090
    

• metrics_listen

  • Constraints / validation: String (optional). When set, must be in IP:PORT format.

  • Description: Full metrics bind address (IP:PORT), overrides metrics_port and binds on the specified address only.

  • Example:

    [server]
    metrics_listen = "127.0.0.1:9090"
    

• metrics_whitelist

  • Constraints / validation: IpNetwork[].

  • Description: CIDR whitelist for metrics endpoint access.

  • Example:

    [server]
    metrics_port = 9090
    metrics_whitelist = ["127.0.0.1/32", "::1/128"]
    

• max_connections

  • Constraints / validation: u32. 0 means unlimited.

  • Description: Maximum number of concurrent client connections.

  • Example:

    [server]
    max_connections = 10000
    

• accept_permit_timeout_ms

  • Constraints / validation: 0..=60000 (milliseconds). 0 keeps legacy unbounded wait behavior.

  • Description: Maximum wait for acquiring a connection-slot permit before the accepted connection is dropped.

  • Example:

    [server]
    accept_permit_timeout_ms = 250
    

Note: When server.proxy_protocol is enabled, incoming PROXY protocol headers are parsed from the first bytes of the connection and the client source address is replaced with src_addr from the header. For security, the peer source IP (the direct connection address) is verified against server.proxy_protocol_trusted_cidrs; if this list is empty, PROXY headers are rejected and the connection is considered untrusted.

[server.conntrack_control]

Note: The conntrack-control worker runs only on Linux. On other operating systems it is not started; if inline_conntrack_control is true, a warning is logged. Effective operation also requires CAP_NET_ADMIN and a usable backend (nft or iptables / ip6tables on PATH). The conntrack utility is used for optional table entry deletes under pressure.

Key	Type	Default
inline_conntrack_control	bool	true
mode	String	"tracked"
backend	String	"auto"
profile	String	"balanced"
hybrid_listener_ips	IpAddr[]	[]
pressure_high_watermark_pct	u8	85
pressure_low_watermark_pct	u8	70
delete_budget_per_sec	u64	4096

• inline_conntrack_control

  • Constraints / validation: bool.

  • Description: Master switch for the runtime conntrack-control task: reconciles raw/notrack netfilter rules for listener ingress (see mode), samples load every second, and may run conntrack -D deletes for qualifying close events while pressure mode is active (see delete_budget_per_sec). When false, notrack rules are cleared and pressure-driven deletes are disabled.

  • Example:

    [server.conntrack_control]
    inline_conntrack_control = true
    

• mode

  • Constraints / validation: One of tracked, notrack, hybrid (case-insensitive; serialized lowercase).

  • Description: tracked: do not install telemt notrack rules (connections stay in conntrack). notrack: mark matching ingress TCP to server.port as notrack — targets are derived from [[server.listeners]] if any, otherwise from server.listen_addr_ipv4 / server.listen_addr_ipv6 (unspecified addresses mean “any” for that family). hybrid: notrack only for addresses listed in hybrid_listener_ips (must be non-empty; validated at load).

  • Example:

    [server.conntrack_control]
    mode = "notrack"
    

• backend

  • Constraints / validation: One of auto, nftables, iptables (case-insensitive; serialized lowercase).

  • Description: Which command set applies notrack rules. auto: use nft if present on PATH, else iptables/ip6tables if present. nftables / iptables: force that backend; missing binary means rules cannot be applied. The nft path uses table inet telemt_conntrack and a prerouting raw hook; iptables uses chain TELEMT_NOTRACK in the raw table.

  • Example:

    [server.conntrack_control]
    backend = "auto"
    

• profile

  • Constraints / validation: One of conservative, balanced, aggressive (case-insensitive; serialized lowercase).

  • Description: When conntrack pressure mode is active (pressure_* watermarks), caps idle and activity timeouts to reduce conntrack churn: e.g. client first-byte idle (client.rs), direct relay activity timeout (direct_relay.rs), and middle-relay idle policy caps (middle_relay.rs via ConntrackPressureProfile::*_cap_secs / direct_activity_timeout_secs). More aggressive profiles use shorter caps.

  • Example:

    [server.conntrack_control]
    profile = "balanced"
    

• hybrid_listener_ips

  • Constraints / validation: IpAddr[]. Required to be non-empty when mode = "hybrid". Ignored for tracked / notrack.

  • Description: Explicit listener addresses that receive notrack rules in hybrid mode (split into IPv4 vs IPv6 rules by the implementation).

  • Example:

    [server.conntrack_control]
    mode = "hybrid"
    hybrid_listener_ips = ["203.0.113.10", "2001:db8::1"]
    

• pressure_high_watermark_pct

  • Constraints / validation: Must be within [1, 100].

  • Description: Pressure mode enters when any of: connection fill vs server.max_connections (percentage, if max_connections > 0), file-descriptor usage vs process soft RLIMIT_NOFILE, non-zero accept_permit_timeout events in the last sample window, or ME c2me send-full counter delta. Entry compares relevant percentages against this high watermark (see update_pressure_state in conntrack_control.rs).

  • Example:

    [server.conntrack_control]
    pressure_high_watermark_pct = 85
    

• pressure_low_watermark_pct

  • Constraints / validation: Must be strictly less than pressure_high_watermark_pct.

  • Description: Pressure mode clears only after three consecutive one-second samples where all signals are at or below this low watermark and the accept-timeout / ME-queue deltas are zero (hysteresis).

  • Example:

    [server.conntrack_control]
    pressure_low_watermark_pct = 70
    

• delete_budget_per_sec

  • Constraints / validation: Must be > 0.

  • Description: Maximum number of conntrack -D attempts per second while pressure mode is active (token bucket refilled each second). Deletes run only for close events with reasons timeout, pressure, or reset; each attempt consumes a token regardless of outcome.

  • Example:

    [server.conntrack_control]
    delete_budget_per_sec = 4096
    

[server.api]

Note: This section also accepts the legacy alias [server.admin_api] (same schema as [server.api]).

Key	Type	Default
enabled	bool	true
listen	String	"0.0.0.0:9091"
whitelist	IpNetwork[]	["127.0.0.0/8"]
auth_header	String	""
request_body_limit_bytes	usize	65536
minimal_runtime_enabled	bool	true
minimal_runtime_cache_ttl_ms	u64	1000
runtime_edge_enabled	bool	false
runtime_edge_cache_ttl_ms	u64	1000
runtime_edge_top_n	usize	10
runtime_edge_events_capacity	usize	256
read_only	bool	false

• enabled

  • Constraints / validation: bool.

  • Description: Enables control-plane REST API.

  • Example:

    [server.api]
    enabled = true
    

• listen

  • Constraints / validation: String. Must be in IP:PORT format.

  • Description: API bind address in IP:PORT format.

  • Example:

    [server.api]
    listen = "0.0.0.0:9091"
    

• whitelist

  • Constraints / validation: IpNetwork[].

  • Description: CIDR whitelist allowed to access API.

  • Example:

    [server.api]
    whitelist = ["127.0.0.0/8"]
    

• auth_header

  • Constraints / validation: String. Empty string disables auth-header validation.

  • Description: Exact expected Authorization header value (static shared secret).

  • Example:

    [server.api]
    auth_header = "Bearer MY_TOKEN"
    

• request_body_limit_bytes

  • Constraints / validation: Must be > 0 (bytes).

  • Description: Maximum accepted HTTP request body size (bytes).

  • Example:

    [server.api]
    request_body_limit_bytes = 65536
    

• minimal_runtime_enabled

  • Constraints / validation: bool.

  • Description: Enables minimal runtime snapshots endpoint logic.

  • Example:

    [server.api]
    minimal_runtime_enabled = true
    

• minimal_runtime_cache_ttl_ms

  • Constraints / validation: 0..=60000 (milliseconds). 0 disables cache.

  • Description: Cache TTL for minimal runtime snapshots (ms).

  • Example:

    [server.api]
    minimal_runtime_cache_ttl_ms = 1000
    

• runtime_edge_enabled

  • Constraints / validation: bool.

  • Description: Enables runtime edge endpoints.

  • Example:

    [server.api]
    runtime_edge_enabled = false
    

• runtime_edge_cache_ttl_ms

  • Constraints / validation: 0..=60000 (milliseconds).

  • Description: Cache TTL for runtime edge aggregation payloads (ms).

  • Example:

    [server.api]
    runtime_edge_cache_ttl_ms = 1000
    

• runtime_edge_top_n

  • Constraints / validation: 1..=1000.

  • Description: Top-N size for edge connection leaderboard.

  • Example:

    [server.api]
    runtime_edge_top_n = 10
    

• runtime_edge_events_capacity

  • Constraints / validation: 16..=4096.

  • Description: Ring-buffer capacity for runtime edge events.

  • Example:

    [server.api]
    runtime_edge_events_capacity = 256
    

• read_only

  • Constraints / validation: bool.

  • Description: Rejects mutating API endpoints when enabled.

  • Example:

    [server.api]
    read_only = false
    

server.listeners

Key	Type	Default
ip	IpAddr	—
announce	String	—
announce_ip	IpAddr	—
proxy_protocol	bool	—
reuse_allow	bool	false

• ip

  • Constraints / validation: Required field. Must be an IpAddr.

  • Description: Listener bind IP.

  • Example:

    [[server.listeners]]
    ip = "0.0.0.0"
    

• announce

  • Constraints / validation: String (optional). Must not be empty when set.

  • Description: Public IP/domain announced in proxy links for this listener. Takes precedence over announce_ip.

  • Example:

    [[server.listeners]]
    ip = "0.0.0.0"
    announce = "proxy.example.com"
    

• announce_ip

  • Constraints / validation: IpAddr (optional). Deprecated. Use announce.

  • Description: Deprecated legacy announce IP. During config load it is migrated to announce when announce is not set.

  • Example:

    [[server.listeners]]
    ip = "0.0.0.0"
    announce_ip = "203.0.113.10"
    

• proxy_protocol

  • Constraints / validation: bool (optional). When set, overrides server.proxy_protocol for this listener.

  • Description: Per-listener PROXY protocol override.

  • Example:

    [server]
    proxy_protocol = false
    
    [[server.listeners]]
    ip = "0.0.0.0"
    proxy_protocol = true
    

• reuse_allow

  • Constraints / validation: bool.

  • Description: Enables SO_REUSEPORT for multi-instance bind sharing (allows multiple telemt instances to listen on the same ip:port).

  • Example:

    [[server.listeners]]
    ip = "0.0.0.0"
    reuse_allow = false
    

[timeouts]

Key	Type	Default
client_handshake	u64	30
relay_idle_policy_v2_enabled	bool	true
relay_client_idle_soft_secs	u64	120
relay_client_idle_hard_secs	u64	360
relay_idle_grace_after_downstream_activity_secs	u64	30
tg_connect	u64	10
client_keepalive	u64	15
client_ack	u64	90
me_one_retry	u8	12
me_one_timeout_ms	u64	1200

• client_handshake

  • Constraints / validation: Must be > 0. Value is in seconds. Also used as an upper bound for some TLS emulation delays (see censorship.server_hello_delay_max_ms).

  • Description: Client handshake timeout (seconds).

  • Example:

    [timeouts]
    client_handshake = 30
    

• relay_idle_policy_v2_enabled

  • Constraints / validation: bool.

  • Description: Enables soft/hard middle-relay client idle policy.

  • Example:

    [timeouts]
    relay_idle_policy_v2_enabled = true
    

• relay_client_idle_soft_secs

  • Constraints / validation: Must be > 0; must be <= relay_client_idle_hard_secs.

  • Description: Soft idle threshold (seconds) for middle-relay client uplink inactivity. Hitting this threshold marks the session as an idle-candidate (it may be eligible for cleanup depending on policy).

  • Example:

    [timeouts]
    relay_client_idle_soft_secs = 120
    

• relay_client_idle_hard_secs

  • Constraints / validation: Must be > 0; must be >= relay_client_idle_soft_secs.

  • Description: Hard idle threshold (seconds) for middle-relay client uplink inactivity. Hitting this threshold closes the session.

  • Example:

    [timeouts]
    relay_client_idle_hard_secs = 360
    

• relay_idle_grace_after_downstream_activity_secs

  • Constraints / validation: Must be <= relay_client_idle_hard_secs.

  • Description: Extra hard-idle grace period (seconds) added after recent downstream activity.

  • Example:

    [timeouts]
    relay_idle_grace_after_downstream_activity_secs = 30
    

• tg_connect

  • Constraints / validation: u64. Value is in seconds.

  • Description: Upstream Telegram connect timeout (seconds).

  • Example:

    [timeouts]
    tg_connect = 10
    

• client_keepalive

  • Constraints / validation: u64. Value is in seconds.

  • Description: Client keepalive timeout (seconds).

  • Example:

    [timeouts]
    client_keepalive = 15
    

• client_ack

  • Constraints / validation: u64. Value is in seconds.

  • Description: Client ACK timeout (seconds).

  • Example:

    [timeouts]
    client_ack = 90
    

• me_one_retry

  • Constraints / validation: u8.

  • Description: Fast reconnect attempts budget for single-endpoint DC scenarios.

  • Example:

    [timeouts]
    me_one_retry = 12
    

• me_one_timeout_ms

  • Constraints / validation: u64. Value is in milliseconds.

  • Description: Timeout per quick attempt (ms) for single-endpoint DC reconnect logic.

  • Example:

    [timeouts]
    me_one_timeout_ms = 1200
    

[censorship]

Key	Type	Default
tls_domain	String	"petrovich.ru"
tls_domains	String[]	[]
unknown_sni_action	"drop" or "mask"	"drop"
tls_fetch_scope	String	""
tls_fetch	Table	built-in defaults
mask	bool	true
mask_host	String	—
mask_port	u16	443
mask_unix_sock	String	—
fake_cert_len	usize	2048
tls_emulation	bool	true
tls_front_dir	String	"tlsfront"
server_hello_delay_min_ms	u64	0
server_hello_delay_max_ms	u64	0
tls_new_session_tickets	u8	0
tls_full_cert_ttl_secs	u64	90
alpn_enforce	bool	true
mask_proxy_protocol	u8	0
mask_shape_hardening	bool	true
mask_shape_hardening_aggressive_mode	bool	false
mask_shape_bucket_floor_bytes	usize	512
mask_shape_bucket_cap_bytes	usize	4096
mask_shape_above_cap_blur	bool	false
mask_shape_above_cap_blur_max_bytes	usize	512
mask_relay_max_bytes	usize	5242880
mask_classifier_prefetch_timeout_ms	u64	5
mask_timing_normalization_enabled	bool	false
mask_timing_normalization_floor_ms	u64	0
mask_timing_normalization_ceiling_ms	u64	0

• tls_domain

  • Constraints / validation: Must be a non-empty domain name. Must not contain spaces or /.

  • Description: Primary TLS domain used in FakeTLS handshake profile and as the default SNI domain.

  • Example:

    [censorship]
    tls_domain = "example.com"
    

• tls_domains

  • Constraints / validation: String[]. When set, values are merged with tls_domain and deduplicated (primary tls_domain always stays first).

  • Description: Additional TLS domains for generating multiple proxy links.

  • Example:

    [censorship]
    tls_domain = "example.com"
    tls_domains = ["example.net", "example.org"]
    

• unknown_sni_action

  • Constraints / validation: "drop" or "mask".

  • Description: Action for TLS ClientHello with unknown / non-configured SNI.

  • Example:

    [censorship]
    unknown_sni_action = "drop"
    

• tls_fetch_scope

  • Constraints / validation: String. Value is trimmed during load; whitespace-only becomes empty.

  • Description: Upstream scope tag used for TLS-front metadata fetches. Empty value keeps default upstream routing behavior.

  • Example:

    [censorship]
    tls_fetch_scope = "fetch"
    

• tls_fetch

  • Constraints / validation: Table. See [censorship.tls_fetch] section below.

  • Description: TLS-front metadata fetch strategy settings (bootstrap + refresh behavior for TLS emulation data).

  • Example:

    [censorship.tls_fetch]
    strict_route = true
    attempt_timeout_ms = 5000
    total_budget_ms = 15000
    

• mask

  • Constraints / validation: bool.

  • Description: Enables masking / fronting relay mode.

  • Example:

    [censorship]
    mask = true
    

• mask_host

  • Constraints / validation: String (optional).

    • If mask_unix_sock is set, mask_host must be omitted (mutually exclusive).
    • If mask_host is not set and mask_unix_sock is not set, Telemt defaults mask_host to tls_domain.

  • Description: Upstream mask host for TLS fronting relay.

  • Example:

    [censorship]
    mask_host = "www.cloudflare.com"
    

• mask_port

  • Constraints / validation: u16.

  • Description: Upstream mask port for TLS fronting relay.

  • Example:

    [censorship]
    mask_port = 443
    

• mask_unix_sock

  • Constraints / validation: String (optional).

    • Must not be empty when set.
    • Unix only; rejected on non-Unix platforms.
    • On Unix, must be (\le 107) bytes (path length limit).
    • Mutually exclusive with mask_host.

  • Description: Unix socket path for mask backend instead of TCP mask_host/mask_port.

  • Example:

    [censorship]
    mask_unix_sock = "/run/telemt/mask.sock"
    

• fake_cert_len

  • Constraints / validation: usize. When tls_emulation = false and the default value is in use, Telemt may randomize this at startup for variability.

  • Description: Length of synthetic certificate payload when emulation data is unavailable.

  • Example:

    [censorship]
    fake_cert_len = 2048
    

• tls_emulation

  • Constraints / validation: bool.

  • Description: Enables certificate/TLS behavior emulation from cached real fronts.

  • Example:

    [censorship]
    tls_emulation = true
    

• tls_front_dir

  • Constraints / validation: String.

  • Description: Directory path for TLS front cache storage.

  • Example:

    [censorship]
    tls_front_dir = "tlsfront"
    

• server_hello_delay_min_ms

  • Constraints / validation: u64 (milliseconds).

  • Description: Minimum server_hello delay for anti-fingerprint behavior (ms).

  • Example:

    [censorship]
    server_hello_delay_min_ms = 0
    

• server_hello_delay_max_ms

  • Constraints / validation: u64 (milliseconds). Must be (<) timeouts.client_handshake * 1000.

  • Description: Maximum server_hello delay for anti-fingerprint behavior (ms).

  • Example:

    [timeouts]
    client_handshake = 30
    
    [censorship]
    server_hello_delay_max_ms = 0
    

• tls_new_session_tickets

  • Constraints / validation: u8.

  • Description: Number of NewSessionTicket messages to emit after handshake.

  • Example:

    [censorship]
    tls_new_session_tickets = 0
    

• tls_full_cert_ttl_secs

  • Constraints / validation: u64 (seconds).

  • Description: TTL for sending full cert payload per (domain, client IP) tuple.

  • Example:

    [censorship]
    tls_full_cert_ttl_secs = 90
    

• alpn_enforce

  • Constraints / validation: bool.

  • Description: Enforces ALPN echo behavior based on client preference.

  • Example:

    [censorship]
    alpn_enforce = true
    

• mask_proxy_protocol

  • Constraints / validation: u8. 0 = disabled, 1 = v1 (text), 2 = v2 (binary).

  • Description: Sends PROXY protocol header when connecting to mask backend, allowing the backend to see the real client IP.

  • Example:

    [censorship]
    mask_proxy_protocol = 0
    

• mask_shape_hardening

  • Constraints / validation: bool.

  • Description: Enables client->mask shape-channel hardening by applying controlled tail padding to bucket boundaries on mask relay shutdown.

  • Example:

    [censorship]
    mask_shape_hardening = true
    

• mask_shape_hardening_aggressive_mode

  • Constraints / validation: Requires mask_shape_hardening = true.

  • Description: Opt-in aggressive shaping profile (stronger anti-classifier behavior with different shaping semantics).

  • Example:

    [censorship]
    mask_shape_hardening = true
    mask_shape_hardening_aggressive_mode = false
    

• mask_shape_bucket_floor_bytes

  • Constraints / validation: Must be > 0; must be <= mask_shape_bucket_cap_bytes.

  • Description: Minimum bucket size used by shape-channel hardening.

  • Example:

    [censorship]
    mask_shape_bucket_floor_bytes = 512
    

• mask_shape_bucket_cap_bytes

  • Constraints / validation: Must be >= mask_shape_bucket_floor_bytes.

  • Description: Maximum bucket size used by shape-channel hardening; traffic above cap is not bucket-padded further.

  • Example:

    [censorship]
    mask_shape_bucket_cap_bytes = 4096
    

• mask_shape_above_cap_blur

  • Constraints / validation: Requires mask_shape_hardening = true.

  • Description: Adds bounded randomized tail bytes even when forwarded size already exceeds cap.

  • Example:

    [censorship]
    mask_shape_hardening = true
    mask_shape_above_cap_blur = false
    

• mask_shape_above_cap_blur_max_bytes

  • Constraints / validation: Must be <= 1048576. Must be > 0 when mask_shape_above_cap_blur = true.

  • Description: Maximum randomized extra bytes appended above cap when above-cap blur is enabled.

  • Example:

    [censorship]
    mask_shape_above_cap_blur = true
    mask_shape_above_cap_blur_max_bytes = 64
    

• mask_relay_max_bytes

  • Constraints / validation: Must be > 0; must be <= 67108864.

  • Description: Maximum relayed bytes per direction on unauthenticated masking fallback path.

  • Example:

    [censorship]
    mask_relay_max_bytes = 5242880
    

• mask_classifier_prefetch_timeout_ms

  • Constraints / validation: Must be within [5, 50] (milliseconds).

  • Description: Timeout budget (ms) for extending fragmented initial classifier window on masking fallback.

  • Example:

    [censorship]
    mask_classifier_prefetch_timeout_ms = 5
    

• mask_timing_normalization_enabled

  • Constraints / validation: When true, requires mask_timing_normalization_floor_ms > 0 and mask_timing_normalization_ceiling_ms >= mask_timing_normalization_floor_ms. Ceiling must be <= 60000.

  • Description: Enables timing envelope normalization on masking outcomes.

  • Example:

    [censorship]
    mask_timing_normalization_enabled = false
    

• mask_timing_normalization_floor_ms

  • Constraints / validation: Must be > 0 when timing normalization is enabled; must be <= mask_timing_normalization_ceiling_ms.

  • Description: Lower bound (ms) for masking outcome normalization target.

  • Example:

    [censorship]
    mask_timing_normalization_floor_ms = 0
    

• mask_timing_normalization_ceiling_ms

  • Constraints / validation: Must be >= mask_timing_normalization_floor_ms; must be <= 60000.

  • Description: Upper bound (ms) for masking outcome normalization target.

  • Example:

    [censorship]
    mask_timing_normalization_ceiling_ms = 0
    

[censorship.tls_fetch]

Key	Type	Default
profiles	String[]	["modern_chrome_like", "modern_firefox_like", "compat_tls12", "legacy_minimal"]
strict_route	bool	true
attempt_timeout_ms	u64	5000
total_budget_ms	u64	15000
grease_enabled	bool	false
deterministic	bool	false
profile_cache_ttl_secs	u64	600

• profiles

  • Constraints / validation: String[]. Empty list falls back to defaults; values are deduplicated preserving order.

  • Description: Ordered ClientHello profile fallback chain for TLS-front metadata fetch.

  • Example:

    [censorship.tls_fetch]
    profiles = ["modern_chrome_like", "compat_tls12"]
    

• strict_route

  • Constraints / validation: bool.

  • Description: When true and an upstream route is configured, TLS fetch fails closed on upstream connect errors instead of falling back to direct TCP.

  • Example:

    [censorship.tls_fetch]
    strict_route = true
    

• attempt_timeout_ms

  • Constraints / validation: Must be > 0 (milliseconds).

  • Description: Timeout budget per one TLS-fetch profile attempt (ms).

  • Example:

    [censorship.tls_fetch]
    attempt_timeout_ms = 5000
    

• total_budget_ms

  • Constraints / validation: Must be > 0 (milliseconds).

  • Description: Total wall-clock budget across all TLS-fetch attempts (ms).

  • Example:

    [censorship.tls_fetch]
    total_budget_ms = 15000
    

• grease_enabled

  • Constraints / validation: bool.

  • Description: Enables GREASE-style random values in selected ClientHello extensions for fetch traffic.

  • Example:

    [censorship.tls_fetch]
    grease_enabled = false
    

• deterministic

  • Constraints / validation: bool.

  • Description: Enables deterministic ClientHello randomness for debugging/tests.

  • Example:

    [censorship.tls_fetch]
    deterministic = false
    

• profile_cache_ttl_secs

  • Constraints / validation: u64 (seconds). 0 disables cache.

  • Description: TTL for winner-profile cache entries used by TLS fetch path.

  • Example:

    [censorship.tls_fetch]
    profile_cache_ttl_secs = 600
    

Shape-channel hardening notes ([censorship])

These parameters are designed to reduce one specific fingerprint source during masking: the exact number of bytes sent from proxy to mask_host for invalid or probing traffic.

Without hardening, a censor can often correlate probe input length with backend-observed length very precisely (for example: 5 + body_sent on early TLS reject paths). That creates a length-based classifier signal.

When mask_shape_hardening = true, Telemt pads the client->mask stream tail to a bucket boundary at relay shutdown:

• Total bytes sent to mask are first measured.
• A bucket is selected using powers of two starting from mask_shape_bucket_floor_bytes.
• Padding is added only if total bytes are below mask_shape_bucket_cap_bytes.
• If bytes already exceed cap, no extra padding is added.

This means multiple nearby probe sizes collapse into the same backend-observed size class, making active classification harder.

What each parameter changes in practice:

• mask_shape_hardening Enables or disables this entire length-shaping stage on the fallback path. When false, backend-observed length stays close to the real forwarded probe length. When true, clean relay shutdown can append random padding bytes to move the total into a bucket.
• mask_shape_bucket_floor_bytes Sets the first bucket boundary used for small probes. Example: with floor 512, a malformed probe that would otherwise forward 37 bytes can be expanded to 512 bytes on clean EOF. Larger floor values hide very small probes better, but increase egress cost.
• mask_shape_bucket_cap_bytes Sets the largest bucket Telemt will pad up to with bucket logic. Example: with cap 4096, a forwarded total of 1800 bytes may be padded to 2048 or 4096 depending on the bucket ladder, but a total already above 4096 will not be bucket-padded further. Larger cap values increase the range over which size classes are collapsed, but also increase worst-case overhead.
• Clean EOF matters in conservative mode In the default profile, shape padding is intentionally conservative: it is applied on clean relay shutdown, not on every timeout/drip path. This avoids introducing new timeout-tail artifacts that some backends or tests interpret as a separate fingerprint.

Practical trade-offs:

• Better anti-fingerprinting on size/shape channel.
• Slightly higher egress overhead for small probes due to padding.
• Behavior is intentionally conservative and enabled by default.

Recommended starting profile:

• mask_shape_hardening = true (default)
• mask_shape_bucket_floor_bytes = 512
• mask_shape_bucket_cap_bytes = 4096

Aggressive mode notes ([censorship])

mask_shape_hardening_aggressive_mode is an opt-in profile for higher anti-classifier pressure.

• Default is false to preserve conservative timeout/no-tail behavior.
• Requires mask_shape_hardening = true.
• When enabled, backend-silent non-EOF masking paths may be shaped.
• When enabled together with above-cap blur, the random extra tail uses [1, max] instead of [0, max].

What changes when aggressive mode is enabled:

• Backend-silent timeout paths can be shaped In default mode, a client that keeps the socket half-open and times out will usually not receive shape padding on that path. In aggressive mode, Telemt may still shape that backend-silent session if no backend bytes were returned. This is specifically aimed at active probes that try to avoid EOF in order to preserve an exact backend-observed length.
• Above-cap blur always adds at least one byte In default mode, above-cap blur may choose 0, so some oversized probes still land on their exact base forwarded length. In aggressive mode, that exact-base sample is removed by construction.
• Tradeoff Aggressive mode improves resistance to active length classifiers, but it is more opinionated and less conservative. If your deployment prioritizes strict compatibility with timeout/no-tail semantics, leave it disabled. If your threat model includes repeated active probing by a censor, this mode is the stronger profile.

Use this mode only when your threat model prioritizes classifier resistance over strict compatibility with conservative masking semantics.

Above-cap blur notes ([censorship])

mask_shape_above_cap_blur adds a second-stage blur for very large probes that are already above mask_shape_bucket_cap_bytes.

• A random tail in [0, mask_shape_above_cap_blur_max_bytes] is appended in default mode.
• In aggressive mode, the random tail becomes strictly positive: [1, mask_shape_above_cap_blur_max_bytes].
• This reduces exact-size leakage above cap at bounded overhead.
• Keep mask_shape_above_cap_blur_max_bytes conservative to avoid unnecessary egress growth.

Operational meaning:

• Without above-cap blur A probe that forwards 5005 bytes will still look like 5005 bytes to the backend if it is already above cap.
• With above-cap blur enabled That same probe may look like any value in a bounded window above its base length. Example with mask_shape_above_cap_blur_max_bytes = 64: backend-observed size becomes 5005..5069 in default mode, or 5006..5069 in aggressive mode.
• Choosing mask_shape_above_cap_blur_max_bytes Small values reduce cost but preserve more separability between far-apart oversized classes. Larger values blur oversized classes more aggressively, but add more egress overhead and more output variance.

Timing normalization envelope notes ([censorship])

mask_timing_normalization_enabled smooths timing differences between masking outcomes by applying a target duration envelope.

• A random target is selected in [mask_timing_normalization_floor_ms, mask_timing_normalization_ceiling_ms].
• Fast paths are delayed up to the selected target.
• Slow paths are not forced to finish by the ceiling (the envelope is best-effort shaping, not truncation).

Recommended starting profile for timing shaping:

• mask_timing_normalization_enabled = true
• mask_timing_normalization_floor_ms = 180
• mask_timing_normalization_ceiling_ms = 320

If your backend or network is very bandwidth-constrained, reduce cap first. If probes are still too distinguishable in your environment, increase floor gradually.

[access]

Key	Type	Default
users	Map<String, String>	{"default": "000…000"}
user_ad_tags	Map<String, String>	{}
user_max_tcp_conns	Map<String, usize>	{}
user_max_tcp_conns_global_each	usize	0
user_expirations	Map<String, DateTime<Utc>>	{}
user_data_quota	Map<String, u64>	{}
user_max_unique_ips	Map<String, usize>	{}
user_max_unique_ips_global_each	usize	0
user_max_unique_ips_mode	"active_window", "time_window", or "combined"	"active_window"
user_max_unique_ips_window_secs	u64	30
replay_check_len	usize	65536
replay_window_secs	u64	120
ignore_time_skew	bool	false

• users

  • Constraints / validation: Must not be empty (at least one user must exist). Each value must be exactly 32 hex characters.

  • Description: User credentials map used for client authentication. Keys are user names; values are MTProxy secrets.

  • Example:

    [access.users]
    alice = "00112233445566778899aabbccddeeff"
    bob   = "0123456789abcdef0123456789abcdef"
    

• user_ad_tags

  • Constraints / validation: Each value must be exactly 32 hex characters (same format as general.ad_tag). An all-zero tag is allowed but logs a warning.

  • Description: Per-user sponsored-channel ad tag override. When a user has an entry here, it takes precedence over general.ad_tag.

  • Example:

    [general]
    ad_tag = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    
    [access.user_ad_tags]
    alice = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
    

• user_max_tcp_conns

  • Constraints / validation: Map<String, usize>.

  • Description: Per-user maximum concurrent TCP connections.

  • Example:

    [access.user_max_tcp_conns]
    alice = 500
    

• user_max_tcp_conns_global_each

  • Constraints / validation: usize. 0 disables the inherited limit.

  • Description: Global per-user maximum concurrent TCP connections, applied when a user has no positive entry in [access.user_max_tcp_conns] (a missing key, or a value of 0, both fall through to this setting). Per-user limits greater than 0 in user_max_tcp_conns take precedence.

  • Example:

    [access]
    user_max_tcp_conns_global_each = 200
    
    [access.user_max_tcp_conns]
    alice = 500   # uses 500, not the global cap
    # bob has no entry → uses 200
    

• user_expirations

  • Constraints / validation: Map<String, DateTime<Utc>>. Each value must be a valid RFC3339 / ISO-8601 datetime.

  • Description: Per-user account expiration timestamps (UTC).

  • Example:

    [access.user_expirations]
    alice = "2026-12-31T23:59:59Z"
    

• user_data_quota

  • Constraints / validation: Map<String, u64>.

  • Description: Per-user traffic quota in bytes.

  • Example:

    [access.user_data_quota]
    alice = 1073741824 # 1 GiB
    

• user_max_unique_ips

  • Constraints / validation: Map<String, usize>.

  • Description: Per-user unique source IP limits.

  • Example:

    [access.user_max_unique_ips]
    alice = 16
    

• user_max_unique_ips_global_each

  • Constraints / validation: usize. 0 disables the inherited limit.

  • Description: Global per-user unique IP limit applied when a user has no individual override in [access.user_max_unique_ips].

  • Example:

    [access]
    user_max_unique_ips_global_each = 8
    

• user_max_unique_ips_mode

  • Constraints / validation: Must be one of "active_window", "time_window", "combined".

  • Description: Unique source IP limit accounting mode.

  • Example:

    [access]
    user_max_unique_ips_mode = "active_window"
    

• user_max_unique_ips_window_secs

  • Constraints / validation: Must be > 0.

  • Description: Window size (seconds) used by unique-IP accounting modes that include a time window ("time_window" and "combined").

  • Example:

    [access]
    user_max_unique_ips_window_secs = 30
    

• replay_check_len

  • Constraints / validation: usize.

  • Description: Replay-protection storage length (number of entries tracked for duplicate detection).

  • Example:

    [access]
    replay_check_len = 65536
    

• replay_window_secs

  • Constraints / validation: u64.

  • Description: Replay-protection time window in seconds.

  • Example:

    [access]
    replay_window_secs = 120
    

• ignore_time_skew

  • Constraints / validation: bool.

  • Description: Disables client/server timestamp skew checks in replay validation when enabled.

  • Example:

    [access]
    ignore_time_skew = false
    

upstreams

Key	Type	Default
type	"direct", "socks4", "socks5", or "shadowsocks"	—
weight	u16	1
enabled	bool	true
scopes	String	""
interface	String	—
bind_addresses	String[]	—
url	String	—
address	String	—
user_id	String	—
username	String	—
password	String	—

• type

  • Constraints / validation: Required field. Must be one of: "direct", "socks4", "socks5", "shadowsocks".

  • Description: Selects the upstream transport implementation for this [[upstreams]] entry.

  • Example:

    [[upstreams]]
    type = "direct"
    
    [[upstreams]]
    type = "socks5"
    address = "127.0.0.1:9050"
    
    [[upstreams]]
    type = "shadowsocks"
    url = "ss://2022-blake3-aes-256-gcm:BASE64PASSWORD@127.0.0.1:8388"
    

• weight

  • Constraints / validation: u16 (0..=65535).

  • Description: Base weight used by weighted-random upstream selection (higher = chosen more often).

  • Example:

    [[upstreams]]
    type = "direct"
    weight = 10
    

• enabled

  • Constraints / validation: bool.

  • Description: When false, this entry is ignored and not used for any upstream selection.

  • Example:

    [[upstreams]]
    type = "socks5"
    address = "127.0.0.1:9050"
    enabled = false
    

• scopes

  • Constraints / validation: String. Comma-separated list; whitespace is trimmed during matching.

  • Description: Scope tags used for request-level upstream filtering. If a request specifies a scope, only upstreams whose scopes contains that tag can be selected. If a request does not specify a scope, only upstreams with empty scopes are eligible.

  • Example:

    [[upstreams]]
    type = "socks4"
    address = "10.0.0.10:1080"
    scopes = "me, fetch, dc2"
    

• interface

  • Constraints / validation: String (optional).

    • For "direct": may be an IP address (used as explicit local bind) or an OS interface name (resolved to an IP at runtime; Unix only).
    • For "socks4"/"socks5": supported only when address is an IP:port literal; when address is a hostname, interface binding is ignored.
    • For "shadowsocks": passed to the shadowsocks connector as an optional outbound bind hint.

  • Description: Optional outbound interface / local bind hint for the upstream connect socket.

  • Example:

    [[upstreams]]
    type = "direct"
    interface = "eth0"
    
    [[upstreams]]
    type = "socks5"
    address = "203.0.113.10:1080"
    interface = "192.0.2.10" # explicit local bind IP
    

• bind_addresses

  • Constraints / validation: String[] (optional). Applies only to type = "direct".

    • Each entry should be an IP address string.
    • At runtime, Telemt selects an address that matches the target family (IPv4 vs IPv6). If bind_addresses is set and none match the target family, the connect attempt fails.

  • Description: Explicit local source addresses for outgoing direct TCP connects. When multiple addresses are provided, selection is round-robin.

  • Example:

    [[upstreams]]
    type = "direct"
    bind_addresses = ["192.0.2.10", "192.0.2.11"]
    

• url

  • Constraints / validation: Applies only to type = "shadowsocks".

    • Must be a valid Shadowsocks URL accepted by the shadowsocks crate.
    • Shadowsocks plugins are not supported.
    • Requires general.use_middle_proxy = false (shadowsocks upstreams are rejected in ME mode).

  • Description: Shadowsocks server URL used for connecting to Telegram via a Shadowsocks relay.

  • Example:

    [general]
    use_middle_proxy = false
    
    [[upstreams]]
    type = "shadowsocks"
    url = "ss://2022-blake3-aes-256-gcm:BASE64PASSWORD@127.0.0.1:8388"
    

• address

  • Constraints / validation: Required for type = "socks4" and type = "socks5". Must be host:port or ip:port.

  • Description: SOCKS proxy server endpoint used for upstream connects.

  • Example:

    [[upstreams]]
    type = "socks5"
    address = "127.0.0.1:9050"
    

• user_id

  • Constraints / validation: String (optional). Only for type = "socks4".

  • Description: SOCKS4 CONNECT user ID. Note: when a request scope is selected, Telemt may override this with the selected scope value.

  • Example:

    [[upstreams]]
    type = "socks4"
    address = "127.0.0.1:1080"
    user_id = "telemt"
    

• username

  • Constraints / validation: String (optional). Only for type = "socks5".

  • Description: SOCKS5 username (for username/password authentication). Note: when a request scope is selected, Telemt may override this with the selected scope value.

  • Example:

    [[upstreams]]
    type = "socks5"
    address = "127.0.0.1:9050"
    username = "alice"
    

• password

  • Constraints / validation: String (optional). Only for type = "socks5".

  • Description: SOCKS5 password (for username/password authentication). Note: when a request scope is selected, Telemt may override this with the selected scope value.

  • Example:

    [[upstreams]]
    type = "socks5"
    address = "127.0.0.1:9050"
    username = "alice"
    password = "secret"