Macos v1.1 porting (please ignore the version in branch name)

[PouriaCh]

Conduit Manager v1.1 - macOS Edition

Summary

This PR introduces v1.1 of Conduit Manager for macOS, bringing feature parity with the Linux edition while implementing macOS-specific optimizations. The implementation eliminates the need for sudo/tcpdump through innovative use of Docker container inspection via /proc/net/tcp.

Key Features

✅ Multi-Container Support

• Scale from 1 to 32 Conduit containers based on hardware capacity
• Per-container configuration (max-clients, bandwidth, CPU, memory limits)
• Individual container management via CLI and Telegram bot
• Dynamic container detection and automatic settings synchronization

✅ Background Tracker Service

• 24/7 network monitoring with country-level GeoIP statistics
• Real-time IP extraction via Docker /proc/net/tcp inspection (no sudo required)
• Cumulative traffic tracking and lifetime IP statistics
• Automatic file ownership management to prevent permission issues
• 60-second update interval (optimized for accuracy and performance)

✅ Telegram Bot Integration

• Automated periodic reports (configurable: 1h, 3h, 6h, 12h, 24h)
• Real-time alerts: high CPU (>90%), high RAM (>90%), container down
• Daily and weekly summaries (optional)
• Custom server labels for multi-server setups

Remote Management Commands:

• /status — Full status report with active clients and top upload countries
• /peers — Show connected & connecting clients (now working on macOS)
• /uptime — Per-container uptime and 24h availability
• /containers — List all containers with detailed stats
• /restart_N, /stop_N, /start_N — Container management

✅ Live Dashboard & Status Display

• Real-time monitoring with 5-second refresh
• Per-country traffic breakdown (TOP 5 active clients, TOP 5 by upload)
• Side-by-side display matching Linux edition format
• Resource usage: CPU (per-core and vCPU), RAM, network throughput

✅ Live Peers by Country (Interactive Map)

• Full-screen display showing TOP 10 countries by traffic
• Real-time active client counts per country
• Cumulative upload/download traffic with percentage bars
• 5-second refresh with synchronized progress bar countdown
• No sudo required (uses Docker container inspection)

macOS-Specific Optimizations

Technical Implementation

1. Docker /proc/net/tcp Inspection (Eliminates sudo/tcpdump)

• Direct read of active TCP connections from within Docker containers
• Hex IP address conversion to decimal format (little-endian)
• Private IP filtering (10.x, 172.16-31.x, 192.168.x, 127.x)
• GeoIP lookup with automatic database path resolution
• Result: Full tracker and Live Map functionality without root privileges

2. Modern Bash via Homebrew

• Automatic installation of bash 5.x for associative array support
• Explicit shebang (#!/opt/homebrew/bin/bash) in generated scripts
• Required for country-level data aggregation in tracker
• Ensures compatibility across macOS versions

3. File Ownership Management

• fix_file_ownership() helper ensures proper permissions
• Handles cases where scripts run with sudo
• Prevents permission errors in background services (tracker, telegram)
• Applies to all persistent data files

4. macOS Command Compatibility

• Removed timeout command dependency (not available by default on macOS)
• Fixed grep patterns for Docker STATS logs: grep "\[STATS\]" (with brackets)
• Proper nohup usage with explicit bash interpreter path
• Robust Docker binary resolution without blocking operations

Bug Fixes from Initial PR

Critical Fixes

• ✅ Fixed Docker logs parsing: changed grep "STATS" to grep "\[STATS\]"
• ✅ Removed timeout command causing hangs on macOS (not in default PATH)
• ✅ Fixed tracker not sourcing settings.conf (container count was defaulting to 1)
• ✅ Fixed tracker using wrong bash version (macOS bash 3.2 doesn't support associative arrays)
• ✅ Fixed GeoIP database path resolution for macOS Homebrew installations
• ✅ Fixed file ownership issues when running commands with sudo

Telegram Bot Fixes

• ✅ Fixed /containers command showing "No stats available yet"
• ✅ Fixed /peers command (now working on macOS via Docker inspection)
• ✅ Re-enabled /peers in command list (was incorrectly disabled for macOS)
• ✅ Fixed duplicate telegram_notify processes causing conflicts

UI/UX Fixes

• ✅ Fixed Live Map countdown sync and progress bar animation (now 5 seconds)
• ✅ Fixed status dashboard showing "fix_file_ownership: command not found"
• ✅ Removed trailing ║ characters from Live Map header text lines
• ✅ Fixed speed column in Live Map (removed due to tracker update frequency)
• ✅ Added "[q] Back" to Live Map header for consistency with Linux
• ✅ Fixed status dashboard exit delay for better responsiveness

Testing Performed

Comprehensive testing on macOS with Apple Silicon (M4):

• ✅ Multi-container deployment (1, 2, 3+ containers tested)
• ✅ Background tracker capturing IPs and GeoIP data without sudo
• ✅ All Telegram bot commands: /status, /peers, /uptime, /containers, /restart_N, /stop_N, /start_N
• ✅ Live dashboard refresh and per-country statistics display
• ✅ Live Peers by Country map (option 11) - no sudo required
• ✅ File ownership persistence across sudo/non-sudo runs
• ✅ Container management via Telegram (start/stop/restart)
• ✅ Resource usage monitoring (CPU per-core + vCPU, RAM, network)
• ✅ GeoIP lookups with Iranian and international IPs
• ✅ Telegram service stability (no duplicate processes)

Documentation Updates

README.md

• ✅ Updated feature list to reflect "no sudo required"
• ✅ Added /peers to Telegram bot commands
• ✅ Updated "What's New" to highlight Docker /proc/net/tcp optimization
• ✅ Removed mentions of tcpdump/sudo requirements
• ✅ Added technical implementation details section
• ✅ Removed "Known Limitations" section (resolved)

Code Comments

• ✅ Documented hex IP conversion logic
• ✅ Explained file ownership management approach
• ✅ Added inline documentation for tracker data flow

Platform Differences (macOS vs Linux)

Feature	Linux	macOS	Notes
Docker	Docker Engine	Docker Desktop	Auto-installed via Homebrew
Network	--network=host	Port publishing (-p)	Required for macOS
Services	systemd	nohup	Background tracker & telegram
Auto-start	systemd unit	Not implemented	Manual start after reboot
Peer tracking	tcpdump	Docker /proc/net/tcp	No sudo needed on macOS
Bash version	Default (4.x+)	Homebrew (5.x)	For associative arrays

Version Information

Current: v1.1.0-Mac
Target Branch: macos-edition (upstream)
Base Branch: macos-v1.2-porting (development)

This release achieves feature parity with the Linux v1.1 edition while optimizing for macOS platform constraints.

Breaking Changes

None. This is purely additive. Existing v1.0.2 macOS installations will seamlessly upgrade to v1.1.

Future Work (v1.2+)

Planned enhancements for future releases:

• Container Management submenu (dedicated UI)
• Settings & Tools submenu (better organization)
• Advanced Stats menu (auto-refreshing breakdowns)
• Info & Help submenu (documentation)
• Peak/Average/History tracking
• Data usage cap feature
• CPU temperature display (macOS sysctl adaptation)
• Tracker auto-regeneration on updates

---

Ready for merge - All features tested and working on macOS Apple Silicon.

[PouriaCh]

Hi @SamNet-dev. This PR is for v1.1-Mac. I started breaking down the features from v1.2 tag and porting them in smaller pieces into macos. Still 3000 lines of code is too much, but it would get smaller as it gets closer to the main branch :)

My goal in this PR is not necessarily match the branch v1.1 tag. It's just a step towards achieving parity. Hope that makes sense.

Please let me know if there is anything missing. Thanks.

[SamNet-dev]

Hi @PouriaCh , thanks for putting up with this and updating. I will take a look as soon as I get a chance. Thank you again. You just make sure it's all good to go, and there are no bugs.

[SamNet-dev]

Hey Pouria, thanks for the solid work on this PR — really appreciate the effort.

I'm heads-down on the Linux version right now so I ran your code through some AI review tools to speed things up. They flagged a few things and I wanted to run them by you before we merge. Can you confirm whether these are actual issues or false positives? If you can confirm, we can move forward.

--- HIGH (must-fix before merge) ---

1. PERSIST_DIR fallback overwritten (installer save_settings)
   The 3-step fallback logic (writable dir → user dir → /tmp) runs correctly, but then 4 duplicate lines right after it reset PERSIST_DIR back to the original path, making the fallback dead code. Looks like a copy-paste artifact.

2. Same bug in installer load_settings
   The fallback is overwritten 3 times in a row. Same copy-paste issue.

3. toggle_tracker() enable branch missing Telegram settings
   The disable branch writes all Telegram config (token, chat_id, interval, alerts, summaries, label) into the inline settings heredoc, but the enable branch only writes the basic container settings. If the save_settings function isn't found for some reason, enabling tracker would wipe Telegram config.

--- MEDIUM (should fix) ---

4. telegram_notify.sh shebang is #!/bin/bash
   The tracker script correctly uses #!/opt/homebrew/bin/bash for bash 5.x, but telegram_notify.sh still uses #!/bin/bash which is bash 3.2 on macOS. This would break the weekly summary "new countries" feature (process substitution with comm).

5. check_alerts() only monitors first container
   docker stats with multiple containers returns one line per container, but the code does | head -1 so only the first container's CPU/RAM is checked. The rest are ignored for alerting.

6. Server label not sanitized before writing to settings.conf
   TELEGRAM_SERVER_LABEL goes straight from user input into settings.conf with double quotes, which gets source'd by bash later. A malicious label like: foo"; rm -rf /; echo "
   could execute arbitrary code. Should validate with a whitelist regex like ^[A-Za-z0-9 _.-]+$

--- LOW (nice to have) ---

7. eval used with docker-inspect-derived values in sync_settings_from_containers — could use printf -v instead for safety
8. Temp files use predictable PID-based names in /tmp/ instead of mktemp
9. grep -c "^conduit" could over-count if other conduit-prefixed containers exist
10. sync_settings_from_containers() called every 5s from show_status(), writing to disk on every dashboard refresh tick

Let me know what you think. If these check out I'll get this merged. Thanks!