v1.4.0-LTS

🛡️ MTProxyMax v1.4.0-LTS Release Notes & Architectural Blueprint

Version: v1.4.0-LTS
Codename: Enterprise Federation & Self-Service Suite
Status: Long Term Support (LTS) — Subsequent updates to 1.4.X will focus strictly on maintenance and bug fixes.

---

🌟 Executive Summary

MTProxyMax v1.4.0-LTS marks the culmination of the core feature roadmap, transforming our platform into a Multi-Tiered, Globally Federated Enterprise Proxy Gateway. We have reached the absolute maximum of features needed for a production-grade proxy manager powered by the Rust engine (telemt). From real-time QoS bandwidth shaping and multi-server federation to automated SSL shields, off-site cloud backups, and self-service Telegram bots, this release provides everything you need in one single, high-performance management script.

Moving forward, the script will be updated if bugs or issues come up. Community contributions, bug reports, and pull requests are warmly welcome! Built with strict adherence to zero-downtime operations, every suite is deep-linked into the script's existing Profile Snapshots (MIGRATION_FILES), Backup & Restore Pipelines (create_backup), and TUI/CLI Routers.

---

🚀 The 5 Enterprise Suites of v1.4 LTS

1. 🏎️ Real-Time QoS Bandwidth Throttling (speed-limit)

• Technology: Linux Kernel Traffic Control (tc), Hierarchical Token Bucket (htb), and Stochastic Fairness Queueing (sfq).
• Mechanism: Maps per-user secret IP connections dynamically (telemt_user_connections_current) to root-level egress/ingress class rates without dropping active TCP connections or restarting the container.
• CLI Commands:
  • mtproxymax speed-limit list — View current per-label bandwidth limits (<label> <down_mbps> <up_mbps>).
  • mtproxymax speed-limit set <label> <down_mbps> [up_mbps] — Assign dedicated bandwidth limits.
  • mtproxymax speed-limit remove <label> — Remove speed restrictions from an account.
  • mtproxymax speed-limit apply — Synchronize kernel tc classes with active IP bindings immediately.
  • mtproxymax speed-limit clear — Flush kernel shaping hierarchy.

2. 🌐 Global Federation & Multi-Server Fleet Dashboard (fleet)

• Technology: Asynchronous multi-node REST polling & JSON metrics aggregation over MTProxy endpoints (/metrics).
• Mechanism: Allows a designated Master node to query remote MTProxyMax slave instances (fleet.conf). Calculates global federation health, pooled bandwidth throughput (Gbps/TB), concurrent connection distribution, and active user footprints across the entire fleet in under 2 seconds (curl --max-time 2).
• CLI & Telegram Commands:
  • mtproxymax fleet status — Display formatted terminal table of global node health and aggregated metrics.
  • mtproxymax fleet collect — Refresh background telemetry (cron friendly).
  • /mp_fleet — Formatted Markdown telemetry report delivered directly via Telegram admin bot.

3. 🔐 Automated Let's Encrypt / SSL Shield (ssl-shield)

• Technology: Automated openssl certificate issuance, ACME / ZeroSSL registration, and TLS SNI verification.
• Mechanism: Automates generation of domain certificates (/opt/mtproxymax/ssl/) and validates FakeTLS domain pools against external certificate transparency and expiration metrics.
• CLI Commands:
  • mtproxymax ssl issue <domain> [email] — Issue / verify SSL certificate for a target domain.
  • mtproxymax ssl status — Inspect certificate validity dates, issuer chains, and auto-renewal posture.
  • mtproxymax ssl clear — Reset certificate directories to default self-generated parameters.

4. ☁️ Automated Off-Site Cloud & Telegram Backups (backup-cloud)

• Technology: Direct Telegram Document API (sendDocument) and multi-cloud rclone object storage sync (S3, Cloudflare R2, Google Drive).
• Mechanism: Deeply integrated into create_backup(). Whenever a manual tarball is created (mtproxymax backup) or triggered via daily cron (run_backup), the resulting archive is automatically encrypted (if enabled) and pushed to off-site cloud storage or an administrative Telegram chat/channel (CLOUD_BACKUP_TARGET).
• CLI Commands:
  • mtproxymax backup-cloud status — Check offloading configuration (CLOUD_BACKUP_MODE).
  • mtproxymax backup-cloud toggle <telegram|rclone|s3> <target> — Configure off-site target destinations.
  • mtproxymax backup-cloud push — Manually push the most recent backup tarball to remote destinations.

5. 📱 Dual-Tier End-User Self-Service Bot Tier (/start, /my_status)

• Technology: Event-driven Telegram Bot Engine (mtproxymax-telegram.sh) with role-based access separation (_check_tg_role).
• Mechanism: Splits bot processing into Public Unauthenticated End-User Tier vs. Protected Admin Control Plane. Users can self-service query their quota without exposing admin operations or requiring manual ticket intervention.
• Public End-User Commands:
  • /start — Self-service portal onboarding menu and interactive help guide.
  • /my_status <label> — Instant lookup of personal data consumption, connection status (Active/Disabled), remaining quota (GB/Unlimited), and account expiration timestamp.
  • /voucher <code> [label] — Instant gift voucher redemption (/redeem alias) that sends unique tg:// proxy links and auto-rendered QR codes directly to the user.
  • /support <msg> — Direct ticket forwarding to proxy support administrators (/reply <chat_id> <ans>).

---

🛠️ Architecture & State Migration Deep-Dive

All new configuration structures and runtime storage paths have been fully registered into the global MIGRATION_FILES array (mtproxymax.sh:L4061):

MIGRATION_FILES=(
    ...
    # v1.4 LTS Suite State Files
    "speed_limits.conf" "fleet.conf" "ssl_config.conf" "cloud_backup.conf"
    "fleet_data" "ssl"
)

Profile Snapshot Guarantee (mtproxymax profile)

Because profile snapshots iterate dynamically over "${MIGRATION_FILES[@]}", any profile saved via mtproxymax profile save <name> will automatically preserve hierarchical QoS speed allocations, federation slave targets, cloud storage keys, and SSL configurations.

Zero-Loss Backup & Restore Guarantee (mtproxymax backup / restore)

The create_backup() archive pipeline automatically includes all v1.4 config files along with /opt/mtproxymax/fleet_data/ and /opt/mtproxymax/ssl/. When restoring via mtproxymax restore <archive>, all QoS rules, SSL certificates, and cloud push schedules are restored seamlessly with precise POSIX permissions (chmod 600).

---

🛡️ Comprehensive Audit & Bug Fix Summary

During a thorough end-to-end audit and runtime simulation of the script, we fixed numerous bugs, race conditions, and edge cases across every subsystem:

• Concurrency & Race Conditions Fixed: Wrapped database and configuration updates in atomic file locks (flock) with temporary file swaps (mktemp + mv), preventing data corruption when CLI commands and Telegram bots update records simultaneously.
• Shell Code Injection Prevention: Replaced source across state files (geofence.conf, decoy.conf, failover.conf, ssl.conf) with secure key-value extraction (grep | cut), preventing arbitrary code execution.
• Narrow Terminal Viewport Crashes Fixed: Added border width checks ([ "$inner" -lt 0 ] && inner=0) across ASCII UI drawing functions (draw_box_top/bottom/sep, draw_line), eliminating printf -1 crashes in narrow terminals or cron pipelines.
• Comma & Pipe CSV Import Compatibility: Hardened secret_import to automatically normalize comma-separated CSV spreadsheets (user,key,...) into internal pipe format (|) during read, resolving import syntax rejection errors.
• Container & Strict-Mode Abort Fixes: Added || true fallbacks across all $(ip route show default ...) network detection subshells so strict-mode execution (set -e) doesn't abort inside minimal or unprivileged containers.

---

📋 Verification & Testing Checklist

To verify the v1.4.0-LTS suite on a live deployment:

1. Verify Syntax Integrity:

   bash -n /opt/mtproxymax/mtproxymax

2. Verify CLI Subcommand Resolution & Help Menu:

   mtproxymax --help | grep -E "(speed-limit|fleet|ssl|backup-cloud|geofence|decoy|failover|eco-mode)"

3. Verify Self-Service Bot Response:
   • Send /start and /my_status <label> to the configured Telegram bot and verify clean markdown card formatting.
4. Test Off-Site Backup Hook:

   mtproxymax backup

   • Verify that backup_cloud_push executes cleanly right before the archive path is returned.